Anatomy of a .desktop File

One of the beautiful things about Linux is that developers tend to be conscientious about the use of technical standards. Freedesktop.org maintains a wide series of standards for X Window System desktops, which apply to Gnome, KDE, LXDE and XFCE (I’m not sure whether Fluxbox implements these standards.) The standard for “desktop entries” is still technically a draft, but is generally accepted by the larger X community.

The .desktop file fills two primary functions: first, it informs the desktop environment how the file is to be handled by the desktop environment with regard to menu placement, display, environmental variables, and similar. In this function, it resides globally in /usr/share/applications/ and for specific users in $HOME/.local/applications. The second function is the direct shortcut on the desktop itself. In this function, it resides in $HOME/Desktop. The same file fills both functions, so if you want to have an application both in the menu and on your desktop, you’ll need to put the .desktop file in two places. Let’s take a closer look, shall we?

The .desktop file is generally in a key,value pair format. This means that, generally speaking, each line will look like this:
key=value
Required Elements

Type – specifies the type of desktop entry. Currently, there are three valid types: Application, Link and Directory.
Name – The name of the specific application or directory. This determines the actual display name for the menu/desktop entry.
Exec – provides the actual command to execute, with associated arguments (if necessary.)
Optional Elements

Version – specifies the version of the Desktop Entry Specification to which the .desktop file conforms (currently 1.0).
Encoding – The encoding for the .desktop file. The standard calls for UTF-8.
GenericName – specifies the generic name of the application.
NoDisplay – This is a boolean (i.e. true/false) element. If set to “true”, it means “this application exists but should not appear in menus.” This is most frequently used to associate an application with MIME types so file managers know how to handle things.
Comment – specifies tooltip entries for the file.
Icon – specifies the icon to be used. This entry supports both icons supported under the FreeDesktop Icon Theme Specification (which I haven’t yet fully grokked) as well as absolute paths.
Hidden – another boolean entry which, if true, essentially treats the application as having been deleted.
OnlyShowIn – If you use multiple desktop environments (say, for instance, you use both Gnome and LXDE) and only want the .desktop entry to apply to a few of the environments, this line specifies the environments in which the entry should apply. This entry is mutually exclusive with NotShowIn.
NotShowIn – As above, but instead of specifying where to display the entry, it displays where NOT to display the entry. This is more useful if you have numerous environments but only want to exclude one or two.
Path – specifies the working directory for an application to run in.
Terminal – a boolean entry which specifies whether or not the application requires a terminal to run.
MimeType – specifies any associated MIME types with this application.
Categories – Categories in which this application should appear in menus. Supported categories vary from system to system, but there is an emerging standard for categories.

Finally, any line beginning with an octothorpe (“#”) is considered a comment.
Putting It All Together

Now that we have all the elements, we can open up any text editor and create a .desktop entry. Here’s a very simple sample:

[Desktop Entry]
Encoding=UTF-8
Version=1.0
Type=Application
Terminal=false
Exec=$HOME/MyApp
Name=My Application
Icon=$HOME/Icons/MyIcon.png

Save your entry (as filename.desktop), then put a copy in $HOME/.local/applications and (if you want) another in $HOME/Desktop. If you did it right (and if you’re running Gnome, KDE or LXDE), your new application should show up in your menu and (possibly) on your desktop.