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.

About these ads

36 thoughts on “Anatomy of a .desktop File

  1. Thank you for this. Not for me personally, but I can point people to this who want a simple explanation of how this works.

    Also, Fluxbox is not standards compliant, but the fm2 menu system is pretty darn close. Openbox is standards compliant from the get go.

  2. Pingback: Links 8/4/2010: Linux Probably Back to the PS3, Ubuntu GNU/Linux Users @ ~12 Million | Techrights
  3. Pingback: GoblinX Project » GoblinX Newsletter, Issue 245 (04/11/2010)
  4. Pingback: Installattion Thunderbird 3 Ubuntu 9.10 | PSchwan
  5. Pingback: Installation Thunderbird 3 Ubuntu 9.10 | PSchwan
  6. This is good info about .desktop files, but it’s missing some important general info. Here’s what I learned trying to create a “start” menu item for a beta build of Mozilla’s SeaMonkey browser.

    a) One of the value-added things a Linux distribution usually does when it packages an app is provide a .desktop file and icons. E.g. look at http://packages.ubuntu.com/maverick/amd64/seamonkey-browser/filelist , you can see a .desktop file and some icon pixmaps. You can extract these files from the package (a separate topic in itself!) and modify them to suit or use them for inspiration, e.g. whether the Exec= line should use %u or %f or something else for the file name to open. (Of course if you installed the package using the distribution’s package manager in the first place, you shouldn’t need to do any of this!)

    b) If you want to create an icon on your desktop for an app, I believe both Gnome and KDE let you do it by dragging a program from their file browser to the desktop or a KDE panel.

    c) If you need to create a start menu item for an app, there’s often a GUI to do it. In KDE run the program `kmenuedit` (“KDE Menu Editor”).

    d) If you create a .desktop file by hand, you’ll have to get your desktop environment to notice your change. The brute-force way to do this is logout and back in, or even restart Linux, but there’s probably a program to rebuild the desktop information. For example, in KDE run the command-line program `kbuildsycoca4`.

    e) I think the desktop looks for the icon file in the Icon= line in $HOME/.local/share/icons , /usr/share/pixmaps, and /usr/share/icons.

    f) Note that if you try to put the .desktop file and icons in their system locations in /usr/share, you’ll need to be the super-user “root”.

    g) This could be Ubuntu-specific, but it seems to have .desktop files and icons in /usr/share/app-install for programs that you *might* install; the distribution uses these in its “Get/Install new software/applications” utility.

    I hope this helps someone!

  7. Pingback: RancidMeat: Shortcut « Misanthropic Geek Dot Net
  8. “specific users in $HOME/.local/applications” : this is actually $HOME/.local/share/applications (“share” is missing). By the way, there seems to be many similarities between $HOME/.local/share and /usr/share. May be $HOME/.local is a kind of /usr.

  9. nice article! anyways, i need to put in an extra command on my skype launcher to make my webcam work properly, however when i add the ff to the Exec line:

    export LIBV4LCONTROL_FLAGS=3 && LD_PRELOAD=/usr/lib32/libv4l/v4l1compat.so skype

    the launcher doesn’t work. any thoughts on this? thanks!

    • To be honest, I’m not entirely sure how you’d go about embedding that in a .desktop file. Personally, I’d write a quick and dirty shell script to handle that, then point the .desktop file at the script.

    • you have to use the _env_ command from coreutils.
      In example:
      Exec=env LIBV4LCONTROL_FLAGS=3 LD_PRELOAD=/usr/lib32/libv4l/v4l1compat.so skype

      HTH

  10. Pingback: How can I get files and folders on CrunchBang 10 Xfce desktop?
  11. Pingback: openSUSE CLI updater
  12. Pingback: TechnoStripe – Auto run a command on startup
  13. Pingback: GNU/Linux .desktop files « Giovanni’s Blog
  14. Pingback: Paraview 3.12 on 64-bit CentOS 5.7 | shocksolution.com
  15. Pingback: Hiding unwanted .desktop entries from the menu | slackalaxy
  16. Pingback: » Changing wallpaper using keyboard shortcut in XFCE.
  17. Pingback: Gnome3 and application shortcuts
    • Like “nobody” said, I think the $HOME environment variable is not available inside a .desktop file. I wish it was, and others. Is there a way to access environment variables in a .desktop file?

  18. Pingback: Adding a printer to Linux Mint, LMDE or Ubuntu: an Encore | /pseudomorph
  19. Pingback: Ubuntu, Gnome Shell e Atalhos - Randômio e Aleatórico
  20. Pingback: Delicious Bookmarks for June 27th through June 30th « Lâmôlabs
  21. Pingback: Autostart di Dropbox in lxde | Appunti Disordinati
  22. Pingback: [xubuntu] .desktop files | Ubuntu InfoUbuntu Info
  23. Pingback: schteck | friziderr
  24. Pingback: Quick Linux Notes | Buzu's Oficial Blog
  25. This post is 4 year old but it’s up in the search results. AFAIK, it contains two errors, can you fix them?

    1. You cannot use $HOME or any bash variable (not even placeholders like ~) in desktop file, you must use the full path

    2. You cannot specify the path for icon location. Instead, copy the icon to ~/.local/share/icons

    Finally, as soon as you save the desktop file the system will be refreshed and be aware of the change. But you can also force the refresh: in Gnome Shell use Alt+2, type r, press Enter.

  26. As you learn more and more about the platform, take notes and
    come up with ideas on how to use it better. Google+ is a social networking site
    that has a range of different features that
    you can use to connect with patients and other healthcare professionals.

    There are different ways on getting invited to Pinterest.

  27. Hello, Mr. Joe. May I translate this article into Indonesian someday? This is the first article, easy to remember, easy to understand, I can find in internet about .desktop file. Thank you.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s