Desktop entries

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

The format of desktop entries is similar to INI files. These must have a .desktop extension, and contain a [Desktop Entry] section. Within the [Desktop Entry] section, keys named Type and Name are required; other keys can optionally define its appearance in the application menu and other behaviors.

The three available Types are:

Type=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 #Desktop entries for applications.
Type=Link defines a shortcut to a URL. Link entries use the .desktop file extension.
Type=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.

Desktop environment support

The following table describes desktop environments' support for various features of the Desktop Entry specification.

Desktop environment	Launcher (Package)	Autostart	Application	Link
Cinnamon	gio (glib2)	No	Yes	No
GNOME
GNOME Flashback
MATE
Deepin	dde-open¹ (deepin-api)	Yes	Partially
Enlightenment	enlightenment_open (enlightenment)
KDE Plasma	kde-open² (kde-cli-tools)	Yes	Yes	Yes
LXDE	pcmanfm (pcmanfm)
LXQt	pcmanfm-qt (pcmanfm-qt)
Xfce	exo-open³ (exo)
Environment-agnostic	gtk-launch⁴ (gtk3)	No	Partially	No
	dex (dex)	Yes	Yes	No
	xdg-open (xdg-utils)	No	Buggy	No
	app2unit⁵ (app2unit^AUR)	No⁶	Yes	Yes
	uwsm app⁵ (uwsm)	No⁶	Yes	No

.desktop files of type Application must have the executable bit set to be launched by dde-open
If KDE_SESSION_VERSION is unset, then kfmclient from konqueror will be used instead. (KDE Plasma should set this variable under any condition, though.)
gio (from glib2) will also be tried
Only if application is in /usr/share/applications
Designed for systemd-managed graphical sessions
Systemd manages XDG autostart natively

Usage

Users commonly interact with desktop entries through the main menu of their desktop environment, such as GNOME's "Activity Overview," or a dock or keystroke launcher like dmenu.

Main menu entries are typically installed by new programs in a system-wide location, but users can create their own in their home directory. Menu entries can be modified with one of the graphical tools mentioned below, or with a plain text editor.

Desktop entries can also be invoked from the command line, with a tool like dex:

$ dex /usr/share/applications/firefox.desktop

Desktop entries for applications

Desktop entries for applications, or .desktop files, are basically comprised of a path to an executable with some metadata. They must have Type=Application and contain at least the Name= and Exec= keys, to locate the executable on disk.

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, and can be used to, for example, hide or change the default icon of a system entry.

Example .desktop file

Following is an example of a .desktop file for launching an application, with comments to explain each key. It is only meant to give an impression and does not show how to utilize all possible entry keys.

System-wide application entries are typically found in /usr/share/applications; you can create your own in ~/.local/share/applications with a text editor, or use one of the available tools to help with that.

Note As discussed above, only the Type and Name keys are required.

~/.local/share/applications/jmemorize.desktop

[Desktop Entry]

# The type as listed above
Type=Application

# The version of the desktop entry specification to which this file conforms
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;

Keys commonly found in application entries

All recognized entries can be found on the freedesktop site. Here are some examples:

Type (required)
defines what type of desktop entry this is, as discussed above (required); commonly Type=Application
Version
specifies which version of the Desktop Entry spec this entry conforms to (optional)
Name (required)
GenericName, Comment and Keywords
the name of the menu item or icon for this entry, along with other descriptive information about it
TryExec and Exec
when Type=Application, these keys specify where to find the program it is intended to run

Although Comment and Keywords are not always exposed by the user interface (e.g. the main menu), they can help user to locate the application based on keywords or concepts. For example:

Name=Pidgin
GenericName=Internet messenger

or

Name=NoteCase
GenericName=Note manager
Comment=NoteCase is a hierarchical note manager (outliner), organizing notes in a tree-like structure

Some best practices:

Name should be the official name of the application, as it would appear in the title bar or "About" box
GenericName is what you would generally call an application that performs this application's functions, i.e., Firefox is a "Web Browser"

The Exec key

The Exec= key in an application entry is typically the name of an executable which is expected to be in the user's search path, but an absolute path can be specified for greater security.

The Exec key accepts several "field codes" which can be used to transmit arguments to the launched program, e.g., when used as a drag-and-drop target, or identified as the preferred application for opening a specific type of file or URL. These arguments are passed to the program such that internal whitespace and shell metacharacters are preserved, so you do not need to worry (as much) about quoting.

Here are the most useful field codes:

Field code (reference)	Expands to
`%`, `%F`	a single filename, or a list of files, each as a separate argument
`%u`, `%U`	a single URL, or a list of URLs
`%i`	two separate arguments to the program: `--icon`, followed by the value of the `Icon`

Flatpak file forwarding

The Exec key for Flatpak applications often contains some syntax unique to flatpak run .

Exec=/usr/bin/flatpak run --command=imhex --file-forwarding net.werwolv.ImHex @@u %U @@

See flatpak-run(1) for the details, but in a nutshell:

--file-forwarding
   […] all arguments that are enclosed between a pair of '@@' arguments are interpreted as
   file paths, exported in the document store, and passed to the command in the form of the
   resulting document path. Arguments between '@@u' and '@@' are considered uris, and any file:
   uris are exported. The exports are non-persistent and with read and write permissions for the
   application.

Context menu actions

Some desktop environments and file managers also register contextual actions with desktop entries, e.g. right-click menu actions for a selected file or files. Pantheon is one example, using a background service called Contractor and desktop entries with a .contract extension.

Here is a simple example using notify-send(1) to send a desktop notification with the path of a selected file:

~/.local/share/contractor/notify-send.contract

[Contractor Entry]
Name=Notify
Icon=dialog-information
Description=Create a notify-send notification with the current filename(s)
# appear in the context menu for every file type except directories
MimeType=!inode;
TryExec=notify-send
# %i is expanded as '--icon <Icon>'!
Exec=notify-send %i -u low "Message from Files" "%F"

Here is a more complex example that will convert any PNG files selected to PNMs in parallel:

~/.local/share/contractor/png-to-pnm.contract

[Contractor Entry]
Name=Convert to PNM
Icon=image-x-generic
Description=Convert PNGs to PPMs
MimeType=image/png;
TryExec=parallel
TryExec=pngtopnm
# from the spec:
# > Note that the general escape rule for values of type string states
# > that the backslash character can be escaped as ("\\") as well and that
# > this escape rule is applied before the quoting rule.
Exec=sh -c 'parallel pngtopnm {} \\> {.}.pnm ::: "$@"' parallel %F

One thing to note from the above is that if either of the TryExec= keys fails, the entry is not shown. It may also be instructive to read what the spec has to say about quoting, but in general it behaves like you are used to from the shell, with the additional requirement that %% must be used to produce a literal %.

When troubleshooting complex command lines, it can be helpful to prefix the Exec command with echo and examine the system logs for the output (e.g. with journalctl -f SYSLOG_IDENTIFIER=org.elementary.Contractor), noting which characters do or do not get passed literally.

Maintenance

Desktop entries for applications are typically put in place by package's installation scripts and need little attention. Over time, though, broken or outdated .desktop files can accumulate, particularly those installed to your home directory.

When the executable named by a desktop entry's Exec= or TryExec= cannot be found on the filesystem, that entry should be hidden from main menus and other launchers automatically. Still, it is worthwhile to do some cleanup of ~/.local/share/applications now and then. The following sections describe how to accomplish that.

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_file.desktop

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 the desktop environment.

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

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

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 tvbrowser^AUR 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:

$HOME/.icons (for backwards compatibility)
$XDG_DATA_DIRS/icons
/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 arronax^AUR 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

jddesktopentryedit^AUR is a graphical program using Qt to edit desktop entries.

MenuLibre

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

LibreMenuEditor

libre-menu-editor^AUR is a graphical program for editing desktop entries that aims to be feature-rich yet beginner-friendly.

It uses GTK with libadwaita and follows GNOME's interface guidelines, but is designed to work on any freedesktop.org compliant desktop environment.

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.

See the gendesk project for more information.

lsdesktopf

lsdesktopf^AUR 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 fbrokendesktop^AUR 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]

This technique can be appropriated to set a per-application desktop theme, provided you always launch that application from the system menu or another launcher which utilizes the desktop entry specification:

~/.local/share/applications/gvim-dark.desktop

...
Exec=/usr/bin/env GTK_THEME=Adwaita:dark gvim -f %F
...

See Dark mode switching for more details.

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.