1. Overview
Desktop entry files are a standard way for creating and ordering graphical user interface (GUI) shortcuts. Most major Linux desktop environments support them. Furthermore, GNOME, KDE, and Xfce all follow the XDG Desktop Entry Specification, a de facto standard.
In this guide, we’ll discuss what desktop entry files are, why they are useful, and how they function. We’ll use the expressions desktop entry files, .desktop files, and entry files interchangeably.
The code in the guide has been tested on Debian 10.10 (Buster) with GNU Bash 5.0.3 and Xfce 4.16. It is POSIX-compliant and should work in any such environment.
2. Description
Desktop entry files contain only text. Although commonly referred to as .desktop files, they do not need an extension. For easy classification, however, they can also have the .desktop or .directory extensions. The standard naming convention for entry files is reverse DNS. For example, an acceptable name can be org.example.AppName.desktop.
To function correctly, desktop entry files must be executable. Users can set this permission via chmod in Linux environments.
Entry files can describe three element types:
- shortcut to application (.desktop extension)
- link to resource (.desktop extension)
- submenu (.directory extension)
These elements function as quick visual access points. Each one is usually manifested as a GUI entry on the desktop or system menu. Where the entry is located depends on the location of the desktop entry file.
3. Location
Like normal files, the user can execute .desktop files where they are created. One of their powers, however, lies in their connection with the GUI.
A directory entry file is best placed on the desktop or in $XDG_DATA_DIRS/applications. If the XDG_DATA_DIRS environment variable is not set, defaults are:
- /usr/share (global)
- ~/.local/share (user-specific)
If we place a .desktop file on the desktop, we are creating a shortcut icon. Similarly, placing a .desktop file in $XDG_DATA_DIRS/applications adds a GUI menu icon for that shortcut. In addition, we use .directory files to create system GUI submenus.
Each of these elements is customizable via attributes (such as name and icon). The attribute values exist in a specific format within the files themselves.
4. Format
Desktop entry files consist of case-sensitive UTF-8 encoded lines in three categories:
- comments
- group headers
- key-value pairs
Comments are blank lines or lines starting with the # character:
# This is a comment
Group header lines denote the start of a group and are formatted like:
[Group Name]
We enclose the group name in square brackets. It cannot contain control characters or other square brackets. The only required group header is [Desktop Entry]. This should be the first non-comment line in the desktop entry file. Group names must be unique within a desktop entry file.
We format key-value pair lines as:
Key=Value
Key names are unique per group and can consist of alphanumeric characters and dashes. Keys define attributes of the desktop entry file or its associated GUI element.
The full list of standard supported keys is in the specifications. For example, here are some commonly used ones:
- Version – Version of the used Desktop Entry Specification
- Comment – used as the tooltip for the GUI entry or icon
- TryExec – path to an executable that confirms the program in Exec is present
- Path – current working directory
- Actions – application actions, different from the default, defined with special group headers
The complexity of desktop entry files can vary. Because of this, standardized tools such as desktop-file-utils exist. They can conveniently validate and install .desktop files per the specification.
To illustrate the mechanism, we’ll go through a simple example.
5. Usage
Suppose we want a desktop shortcut for GNOME’s gedit application. Specifically, we want gedit to start with a given file (/home/user/file) already open.
5.1. File Creation
Towards this end, let’s create a simple text file:
[Desktop Entry]
Type=Application
Name=Personal File
Exec=gedit /home/user/file
Icon=gedit
We name this file com.baeldung.starter.GeditPersonal.desktop and place it on the desktop. As a consequence, a new desktop icon with the name “Personal File” and the icon of gedit appears. Finally, we make com.baeldung.starter.GeditPersonal.desktop executable:
$ chmod +x /home/user/Desktop/com.baeldung.starter.GeditPersonal.desktop
Now the user can click the desktop icon to open /home/user/file with gedit. Let’s explore how we achieved this.
5.2. Explanation
Initially, we start off with the group header [Desktop Entry]. It allows desktop entry file (magic) detection even without an extension. Furthermore, [Desktop Entry] normally contains the main portion of the desktop entry file. Under the group header, we list our key-value pairs.
First, we define the category of desktop entry file via the required Type key. It can have the values (1) Application, (2) Link, or (3) Directory. For instance, we define shortcuts to URLs via the Link type. On the other hand, the Directory type defines a system GUI submenu.
Additionally, Application desktop entry files like ours usually have an Exec key. The Exec value contains the command line for execution via the shortcut.
Since applications can take arguments, desktop entries should also have a mechanism to do so. In short, this is done via specifiers in the Exec value such as:
- %f single filename
- %u single URL
- %k URI or local filename of the location of the desktop file
For example, the following format allows us to pass a file directly to the desktop entry file:
Exec=cat %f
We do this via drag-and-drop or the command line. The argument we supply will follow the cat (concatenate) command. We can use the %F, %u, and %U specifiers similarly.
In contrast, the %k specifier provides a way for us to use the location of the desktop file itself in the Exec command line.
Finally, an optional Icon key defines the icon. The Icon value can be a path to one of several supported image formats or an executable. More complex cases are discussed in the Icon Theme Specification standard.
We supply a descriptive name via the required Name key. This name visually replaces the default filename of the desktop entry file.
In addition, an important feature of the Name value is localization.
6. Localization
We can localize some values in desktop entry files. This allows us to display certain translations in certain linguistic environments.
The localization format follows the pattern:
Key[lang_COUNTRY.ENCODING@MODIFIER]=Value
Here’s an example of a localized Name alternative in its simplest form:
Name=Personal File
Name[bg]=Личен Файл
Translations depend on the LC_MESSAGES environment variable. In this example, if it includes bg (Bulgarian), Name will be “Личен файл”.
Using modifiers, we can achieve more precise control. Here’s another example that specifies the country, encoding, and modifier:
Name=Financial Sheets
Name[bg_BG.UTF-8@Iztok]=Финансови Отчети
This locale will match LC_MESSAGES in the following order:
- lang_COUNTRY@MODIFIER
- lang_COUNTRY
- lang@MODIFIER
- lang
- default value
The ENCODING does not take part in the matching.
7. Summary
In this guide, we discussed desktop entry files. First, we defined what they are and where they’re located. Next, we explained their format and usage. Lastly, we discussed an important feature of desktop entry files – localization.