Desktop Entry Specification

Both the KDE and GNOME desktop environments have adopted a similar format for "desktop entries", or configuration files describing how a particular program is to be launched, how it appears in menus, etc. It is to the larger community's benefit that a unified standard be agreed upon by all parties such that interoperation between the two environments, and indeed any additional environments that implement the specification, becomes simpler.

These desktop entry files should have the extension .desktop. Determining file type on basis of extension makes determining the file type very easy and quick. When no file extension is present, the desktop system should fall back to recognition via "magic detection". Desktop entries which describe how a directory is to be formatted/displayed should be simply called .directory.

The basic format of the desktop entry file requires that there be a "group" header named [Desktop Entry]. This "group" entry denotes that all {key,value} pairs following it belong in the Desktop Entry group. There may be other groups present in the file, but this is the most important group which explicitly needs to be supported. This group should also be used as the "magic key" for automatic MIME type detection. There should be nothing proceeding this group in the desktop entry file but possibly one or more comments (see below).

Group headers may not contain the characters [ and ] as those delimit the header.

Lines beginning with a # and blank lines are considered comments and will be ignored, however they should be preserved across reads and writes of the desktop entry file.

Compliant implementations MUST not remove any fields from the file, even if they don't support them. Such fields must be maintained in a list somewhere, and if the file is "rewritten", they will be included. This ensures that any desktop-specific extensions will be preserved even if another system accesses and changes the file.

Entries in the file are {key,value} pairs in the format:

Key=Value

Space before and after the equals sign should be ignored; the = sign is the actual delimiter.

The escape sequences \s, \n, \t, \r, and \\ are supported, meaning ASCII space, newline, tab, carriage return, and backslash, respectively.

The value types recognized are string, localestring, regexp, boolean (encoded as the string true/false), and numeric.

Values of type string must contain only ASCII characters excluding control characters. Values of type localestring are user displayable, and are encoded in UTF-8 unless the Legacy-Mixed Encoding is specified (see Appendix D, The Legacy-Mixed Encoding (Deprecated).)

Some keys can have multiple values; these should be separated by a semicolon. Those keys which have several values should have a semicolon as the trailing character. Semicolons in these values need to be escaped using \;.

Keys with type localestring may be postfixed by [LOCALE], where LOCALE is the locale type of the entry. LOCALE must be of the form lang_COUNTRY.ENCODING@MODIFIER, where _COUNTRY, .ENCODING, and @MODIFIER may be omitted. If a postfixed key occurs, the same key must be also present without the postfix.

When reading in the desktop entry file, the value of the key is selected by matching the current POSIX locale for the LC_MESSAGES category against the LOCALE postfixes of all occurrences of the key, with the .ENCODING part stripped. The .ENCODING field is used only when the value of the Encoding key for the desktop entry file is Legacy-Mixed (see Appendix D, The Legacy-Mixed Encoding (Deprecated).)

The matching of is done as follows. If LC_MESSAGES is of the form lang_COUNTRY.ENCODING@MODIFIER, then it will match a key of the form lang_COUNTRY@MODIFIER. If such a key does not exist, it will attempt to match lang_COUNTRY followed by lang@MODIFIER. Then, a match against lang by itself will be attempted. Finally, if no matching key is found the required key without a locale specified is used. The encoding from the LC_MESSAGES value is ignored when matching.

If LC_MESSAGES does not have a MODIFIER field, then no key with a modifier will be matched. Similarly, if LC_MESSAGES does not have a COUNTRY field, then no key with a country specified will be matched. If LC_MESSAGES just has a lang field, then it will do a straight match to a key with a similar value. The following table lists possible matches of various LC_MESSAGES values in the order in which they are matched. Note that the ENCODING field isn't shown.

For example, if the current value of the LC_MESSAGES category is sr_YU@Latn and the desktop file includes:

 Name=Foo
 Name[sr_YU]=...
 Name[sr@Latn]=...
 Name[sr]=...

then the value of the Name keyed by sr_YU is used.

Case is significant. The keys Name and NAME are not equivalent. The same holds for group names. Key values are case sensitive as well.

Keys are either OPTIONAL or REQUIRED. If a key is optional it may or may not be present in the file. However, if it isn't, the implementation of the standard should not blow up, it must provide some sane defaults. Additionally, keys either MUST or MAY be supported by a particular implementation.

Some keys only make sense in the context when another particular key is also present.

Some example keys: Name[C], Comment[it].

Desktop entry files are encoded as lines of 8-bit characters separated by LF characters.

Comment lines are uninterpreted and may contain any character (except for LF). However, using UTF-8 for comment lines that contain characters not in ASCII is encouraged.

The encoding for values of type localestring is determined by the Encoding field.

Each Exec field may take a number of arguments which will be expanded by the file manager or program launcher and passed to the program if necessary.

Literal % characters must be escaped as %%, and adding new format characters is not allowed. It's a fatal error to have an Exec field with a format character not given in the spec (exception to this are the deprecated format characters which can be ignored, that is expanded to no parameters, by the implementation). Again for emphasis: nonstandard extensions are not allowed here - you must add an X-Foo-Exec field if you have nonstandard Exec lines.

The escaping of the exec parameters is done in the way the mailcap specification describes. Take a look at RFC 1524 for more information.

Recognized fields are as follows:

The MimeType key is used to indicate the MIME Types that an application knows how to handle. Applications that can handle multiple MIME Types would list all of the ones it can handle in a ';' separated list, as normal. It is expected that for some applications this list could become long. An application is expected to be able to reasonably open files of these types using the command listed in the Exec keyword.

There should be no priority for MIME Types in this field, or any form of priority in the desktop file. Priority for applications is handled external to the .desktop files.

application/x-foo=foo.desktop;bar.desktop;
application/x-bar=bar.desktop;

mime/type=desktop-id.desktop;

If the standard is to be amended with a new {key,value} pair which should be applicable to all supporting parties, a group discussion will take place. This is the preferred method for introducing changes. If one particular party wishes to add a field for personal use, they should prefix the key with the string X-PRODUCT, e.g. X-NewDesktop-Foo, following the precedent set by other IETF and RFC standards.

Alternatively, fields can be placed in their own group, where they may then have arbitrary key names. If this is the case, the group should follow the scheme outlined above, i.e. [X-PRODUCT GROUPNAME] or something similar. These steps will avoid namespace clashes between different yet similar environments.