KDE uses a simple text-based file format for all its configuration files. It consists of key-value pairs that are placed in groups. All KDE configuration files use UTF-8 encoding for text outside the ASCII range.

The start of a group is indicated by a group name that is placed in square brackets. All the key-value entries that follow belong to the group. The group ends when either another group starts or when the end of the file is reached. Entries at the top of the file that are not preceded by a group name belong to the default group.

[KDE]
LargeCursor=false
SingleClick=true

[KFileDialog Settings]
Show hidden files=false
Sort by=Name

Entries in a group consist of a key and value separated by an equals sign. The key can contain spaces and may be followed by options placed in square brackets. The part after the equals sign is the value of the entry. Any white space surrounding the equals sign is ignored, as is any trailing white space. Put more concisely, the format is:

entry=value

If a value is supposed to include a space at the begin or end then this can be achieved by using a backslash followed by an “s”.

There are several other backslash codes; here is a complete list:

[Preview Image]
Caption=\s My Caption
Description=This is\na very long\ndescription.

Empty lines in configuration files are ignored, as are lines that start with a hash mark (“#”). The hash mark can be used to add comments to configuration files. It should be noted that when a KDE application updates a configuration file the comments are not preserved.

There can be multiple configuration files with the same name in the share/config sub-directory of the various KDE directory trees. In this case the information of all these configuration files is combined on a key-by-key basis. If the same key within a certain group is defined in more than one place, the key value read from the directory tree with the highest precedence will be used. Configuration files under $KDEHOME always have the highest precedence. If a key in a certain group is defined multiple times in a single file, the value of the last entry is used.

[MyGroup]
Color=red
Shape=circle

[MyGroup]
Color=blue
Position=10,10

[MyGroup]
Color=red
Shape=circle
Position=10,10

[MyGroup]
Color=red
Shape=circle
[MyGroup]
Color=green

[MyGroup]
Color=purple
Position=20,20

[MyGroup]
Color=blue
Position=10,10

[MyGroup]
Color=green
Shape=circle
Position=20,20

To prevent users being able to override default settings, settings can be marked immutable. Settings can be made immutable individually, per group or per file. An individual entry can be locked down by adding [$i] behind the key, e.g.:

Color[$i]=blue

A group of entries can be locked down by placing [$i] behind the group name, e.g.:

[MyGroup][$i]

To lock down the entire file, start the file with [$i] on a single line, i.e.:

[$i]

[MyGroup]
Color=red
Shape=circle

[MyGroup][$i]
Color=blue
Position=10,10

[MyGroup]
Color=blue
Position=10,10

[MyGroup]
Color=red
Shape=circle

[MyGroup]
Color=purple
Shape=rectangle

[MyGroup][$i]
Color=blue
Position=10,10

[MyGroup]
Color=purple
Shape=rectangle
Position=10,10

So-called “Shell Expansion” can be used to provide more dynamic default values. With shell expansion the value of a configuration key can be constructed from the value of an environment variable or from the output of a shell command. To enable shell expansion for a configuration entry, the key must be followed by [$e]. Normally the expanded form is written into the user's configuration file after first use. To prevent that, it is recommend to lock the configuration entry down by using [$ie]. The user can't change it then of course.

[Mail Settings] 
Host[$ie]=$(hostname)
Email[$e]=${USER}@${HOST}

Most configuration entries can be indexed with a language code. In this case, the language that the user has selected for use on the desktop is used to look up the key value. If the default language (American English) has been selected or if there is no index that corresponds to the selected language, the key entry without index is used.

[Preview Image]
Caption=My Caption
Caption[fr]=Ma Légende

[Preview Image]
Caption=My Caption
Caption[fr]=Ma Légende

In general the entries that can appear in a configuration file are not documented. With KDE 3.2 a start has been made to change this. In $KDEDIR/share/config.kcfg, files can be found that provide a formal description of the possible entries in a configuration file. These are used by the new KDE Configuration Editor when available.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM "http://www.kde.org/standards/kcfg/1.0/kcfg.dtd">
<kcfg>
    <kcfgfile name="korganizerrc"/>
    <group name="General">
         <entry type="Bool" key="Auto Save">
             <label>Enable automatic saving of calendar</label>
             <default>true</default>
         </entry>
         <entry type="Int" key="Auto Save Interval">
             <default>10</default>
         </entry>
    </group>
</kcfg>

[General]
Auto Save=false
Auto Save Interval=25