Desktop entries

From ArchWiki

The XDG Desktop Entry specification defines a standard for applications to integrate into application menus of desktop environments implementing the XDG Desktop Menu specification.

Basics

Each desktop entry must have a Type and a Name key and can optionally define its appearance in the application menu.

The three available types are:

Application
Defines how to launch an application and what MIME types it supports (used by XDG MIME Applications). With XDG Autostart Application entries can be started automatically by placing them in specific directories. Application entries use the .desktop file extension. See #Application entry.
Link
Defines a shortcut to a URL. Link entries use the .desktop file extension.
Directory
Defines the appearance of a submenu in the application menu. Directory entries use the .directory file extension.

The following sections will roughly explain how these are created and validated.

Usage

Use a desktop opener like dex: 

$ dex /usr/share/applications/firefox.desktop
Desktop environment Launcher
(Package) 		Autostart Application Link
Cinnamon gio
(glib2) 		No Yes No
GNOME
GNOME Flashback
MATE
Deepin dde-open1
(deepin-api) 		Yes Partially
Enlightenment enlightenment_open
(enlightenment)
KDE Plasma kde-open2
(kde-cli-tools) 		Yes Yes Yes
LXDE pcmanfm
(pcmanfm)
LXQt –
Xfce exo-open3
(exo)
Environment-agnostic gtk-launch4
(gtk3) 		No Partially No
dex
(dex) 		Yes Yes No
xdg-open
(xdg-utils) 		No Buggy No
  1. .desktop files of type Application must have the executable bit set to be launched by dde-open
  2. If KDE_SESSION_VERSION is unset, then kfmclient from konqueror will be used instead. (KDE Plasma should set this variable under any condition, though.)
  3. gio (from glib2) will also be tried
  4. Only if application is in /usr/share/applications

Application entry

Desktop entries for applications, or .desktop files, are generally a combination of meta information resources and a shortcut of an application. These files usually reside in /usr/share/applications/ or /usr/local/share/applications/ for applications installed system-wide, or ~/.local/share/applications/ for user-specific applications. User entries take precedence over system entries.

File example

Following is an example of its structure with additional comments. The example is only meant to give a quick impression, and does not show how to utilize all possible entry keys. The complete list of keys can be found in the freedesktop specification. 

[Desktop Entry]

# The type as listed above
Type=Application

# The version of the desktop entry specification to which this file complies
Version=1.0

# The name of the application
Name=jMemorize

# A comment which can/will be used as a tooltip
Comment=Flash card based learning tool

# The path to the folder in which the executable is run
Path=/opt/jmemorise

# The executable of the application, possibly with arguments.
Exec=jmemorize

# The name of the icon that will be used to display this entry
Icon=jmemorize

# Describes whether this application needs to be run in a terminal or not
Terminal=false

# Describes the categories in which this entry should be shown
Categories=Education;Languages;Java;
Note: Only Type and Name are required.

Key definition

All recognized entries can be found on the freedesktop site. For example, the Type key defines three types of desktop entries: Application (type 1), Link (type 2) and Directory (type 3).

  • Version key does not stand for the version of the application, but for the version of the desktop entry specification to which this file complies.
  • Name, GenericName and Comment often contain redundant values in the form of combinations of them, like:
Name=Pidgin Internet Messenger
GenericName=Internet Messenger

or 

Name=NoteCase notes manager
Comment=Notes Manager

This should be avoided, as it will only be confusing to users. The Name key should only contain the name, or maybe an abbreviation/acronym if available.

  • GenericName should state what you would generally call an application that does what this specific application offers (i.e. Firefox is a "Web Browser").
  • Comment is intended to contain any useful additional information.

Validation

As some keys have become deprecated over time, you may want to validate your desktop entries using desktop-file-validate(1) which is part of the desktop-file-utils package. To validate, run: 

$ desktop-file-validate <your desktop file>

This will give you very verbose and useful warnings and error messages.

Installation

Use desktop-file-install(1) to install desktop file into target directory. For example: 

$ desktop-file-install --dir=$HOME/.local/share/applications ~/app.desktop

This is also useful for customizing existing desktop entries (e.g. from /usr/share/applications) via edit options.

Update database of desktop entries

Usually, desktop entry changes are automatically picked up by desktop environments.

If this is not the case, and you want to forcefully update the desktop entries defined in ~/.local/share/applications, run the following command: 

$ update-desktop-database ~/.local/share/applications
Tip: Add the -v (verbose) argument to show possible desktop entry errors.

Icons

See also the Icon Theme Specification.

Common image formats

Here is a short overview of image formats commonly used for icons.

Support for image formats for icons as specified by the freedesktop.org standard.
Extension Full Name and/or Description Graphics Type Container Format Supported
.png Portable Network Graphics Raster No Yes
.svg(z) Scalable Vector Graphics Vector No Yes (optional)
.xpm X PixMap Raster No Yes (deprecated)
.gif Graphics Interchange Format Raster No No
.ico MS Windows Icon Format Raster Yes No
.icns Apple Icon Image Raster Yes No

Converting icons

This article or section is a candidate for merging with ImageMagick#Usage.

Notes: Belongs there. (Discuss in Talk:Desktop entries)

If you stumble across an icon which is in a format that is not supported by the freedesktop.org standard (like gif or ico), you can use the convert tool (which is part of the imagemagick package) to convert it to a supported/recommended format, e.g.: 

$ convert <icon name>.gif <icon name>.png

If you convert from a container format like ico, you will get all images that were encapsulated in the ico file in the form <icon name>-<number>.png. If you want to know the size of the image, or the number of images in a container file like ico you can use the identify tool (also part of the imagemagick package): 

$ identify /usr/share/vlc/vlc48x48.ico
/usr/share/vlc/vlc48x48.ico[0] ICO 32x32 32x32+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[1] ICO 16x16 16x16+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[2] ICO 128x128 128x128+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[3] ICO 48x48 48x48+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[4] ICO 32x32 32x32+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[5] ICO 16x16 16x16+0+0 8-bit DirectClass 84.3kb

As you can see, the example ico file, although its name might suggest a single image of size 48x48, contains no less than 6 different sizes, of which one is even greater than 48x48, namely 128x128.

Alternatively, you can use icotool (from icoutils) to extract png images from ico container: 

$ icotool -x <icon name>.ico

For extracting images from .icns container, you can use icns2png (provided by libicns): 

$ icns2png -x <icon name>.icns

Obtaining icons

Although packages that already ship with a .desktop file most certainly contain an icon or a set of icons, there is sometimes the case when a developer has not created a .desktop file, but may ship icons, nonetheless. So a good start is to look for icons in the source package. You can i.e. first filter for the extension with find and then use grep to filter further for certain buzzwords like the package name, "icon", "logo", etc, if there are quite a lot of images in the source package. 

$ find /path/to/source/package -regex ".*\.\(svg\|png\|xpm\|gif\|ico\)$"

If the developers of an application do not include icons in their source packages, the next step would be to search on their web sites. Some projects, like i.e. tvbrowserAUR have an artwork/logo page where additional icons may be found. If a project is multi-platform, there may be the case that even if the linux/unix package does not come with an icon, the Windows package might provide one. If the project uses a Version control system like CVS/SVN/etc. and you have some experience with it, you also might consider browsing it for icons. If everything fails, the project might simply have no icon/logo yet.

Icon path

The freedesktop.org standard specifies in which order and directories programs should look for icons:

  1. $HOME/.icons (for backwards compatibility)
  2. $XDG_DATA_DIRS/icons
  3. /usr/share/pixmaps

Tools

This article or section needs language, wiki syntax or style improvements. See Help:Style for reference.

Reason: Use a list of Template:App entries instead of short sections. (Discuss in Talk:Desktop entries)

Arronax

Arronax is a graphical program to create and modify desktop entries for applications and locations. Install the arronaxAUR package to use it.

Alacarte

alacarte is a graphical menu editor for GNOME using the freedesktop.org menu specification. It also supports overriding desktop entries.

jdDesktopEntryEdit

jddesktopentryeditAUR is a graphical program using Qt to edit desktop entries.

MenuLibre

menulibreAUR is a graphical menu editor using GTK that provides modern features in a clean, easy-to-use interface.

gendesk

gendesk started as an Arch Linux-specific tool for generating .desktop files by fetching the needed information directly from PKGBUILD files. Now it is a general tool that takes command-line arguments.

Icons can be automatically downloaded from openiconlibrary, if available. (The source for icons is configurable).

How to use

  • Add gendesk to makedepends
  • Start the prepare() function with:
gendesk --pkgname "$pkgname" --pkgdesc "$pkgdesc"
  • Alternatively, if an icon is already provided ($pkgname.png, for instance). The -n flag is for not downloading an icon or using the default icon. Example:
gendesk -n --pkgname "$pkgname" --pkgdesc "$pkgdesc"
  • $srcdir/$pkgname.desktop will be created and can be installed in the package() function with:
install -Dm644 "$pkgname.desktop" "$pkgdir/usr/share/applications/$pkgname.desktop"
  • The icon can be installed with:
install -Dm644 "$pkgname.png" "$pkgdir/usr/share/pixmaps/$pkgname.png"
  • Use --name='Program Name' for choosing a name for the menu entry.
  • Use --exec='/opt/some_app/elf --some-arg --other-arg' for setting the exec field.

lsdesktopf

lsdesktopfAUR can list available .desktop files or search their contents. 

$ lsdesktopf
$ lsdesktopf --list
$ lsdesktopf --list gtk zh_TW,zh_CN,en_GB

It can also perform MIME-type-related searches. See XDG MIME Applications#lsdesktopf.

fbrokendesktop

The fbrokendesktopAUR Bash script detects broken Exec values pointing to non-existent paths. Without any arguments it uses preset directories in the DskPath array. It shows only broken .desktop with full path and filename that is missing.

Examples: 

$ fbrokendesktop
$ fbrokendesktop /usr
$ fbrokendesktop /usr/share/xsessions/icewm.desktop

Tips and tricks

Modify desktop files

For system-wide .desktop files (e.g. those installed from a package), first copy the relevant .desktop file (e.g. from /usr/share/applications/) to $XDG_DATA_HOME/applications/ (e.g. ~/.local/share/applications/). This prevents your changes from being overwritten when the package gets updated during system upgrades. The local user-specific .desktop files should automatically take precedence over the system-wide files. Now you can modify the local user-specific .desktop file as needed.

Note: If you have configured this application to autostart, there may already be a copy of the system desktop entry in $XDG_CONFIG_HOME/autostart, as per XDG Autostart. If you want to modify the behavior only while autostarting, proceed to edit this file. Otherwise, if you want to modify the behavior in all circumstances, you should:
  • Move the desktop file from $XDG_CONFIG_HOME/autostart/ to $XDG_DATA_HOME/applications.
  • Using ls -l, make sure that this desktop entry is a regular file you can edit, and not a link to the system location. If it is a link, replace it with a copy of the original as described above.
  • Make a symbolic link to the user application directory (default XDG dirs substituted for convenience):
ln -s ~/.local/share/applications/desktop_entry ~/.config/autostart/

Now, the file in your application launcher will stay the same as the one that is autostarted.

Modify environment variables

To set environment variables, in the .desktop file, edit the Exec= line to first use the env(1) command to set your variables. For example, with the original line commented out: 

~/.local/share/applications/abiword.desktop
...
# Exec=abiword %U
Exec=env LANG=he_IL.UTF-8 abiword %U
...

Also remove DBusActivatable=true (or set it to false) if present as it will cause the Exec line to be ignored.[1]

Modify command line arguments

To change or add the command line arguments, edit the Exec= line to append the desired options. As an example, with the original line commented out: 

~/.local/share/applications/steam.desktop
...
# Exec=/usr/bin/steam-runtime %U
Exec=/usr/bin/steam-runtime -no-browser %U
...

Also remove DBusActivatable=true (or set it to false) if present as it will cause the Exec line to be ignored.[2]

Hide desktop entries

The visibility of the desktop entry can be controlled in multiple ways. See the Desktop Entry Specification for more information. Add one of the following lines to your .desktop file:

  • All desktop environments, choose one (or both) of the following:
    • Add the line NoDisplay=true for applications that you do not want displayed in the menus.
    • Add the line Hidden=true for applications that you consider deleted and do not want displayed in the menus.
  • Specified desktop environments, choose one of the following where desktop_names is a semicolon-delimited list of desktop environments (e.g. GNOME, GNOME;Xfce;KDE;):
    • Add the line NotShowIn=desktop_names to hide the entry only in the specified desktop environments.
    • Add the line OnlyShowIn=desktop_names to show the entry only in the specified desktop environments.

See also