Modifying desktop files in GNOME requires careful attention to syntax and permissions because the desktop entry specification is strict. Incorrect formatting, such as using invalid shell wrappers or missing fields, prevents applications from launching correctly. This guide details the correct structure for .desktop files, proper execution commands, and troubleshooting steps for common GNOME integration errors.
Understanding the Desktop Entry Specification
A desktop file, typically ending in
.desktop, serves as a metadata container that allows the operating system to integrate third-party applications into the application menu and launcher. These files follow the Desktop Entry Specification defined by freedesktop.org. The most critical section is
[Desktop Entry], which contains key-value pairs that define how the application behaves.
Common keys include
Type, which must be set to
Application;
Name, which displays the title in menus; and
Exec, which defines the command line used to launch the program. Another vital field is
Icon, which points to the image file displayed in the interface. If any of these fields are malformed, GNOME will often ignore the file entirely or fail to execute the application silently.
It is important to note that these files are not scripts themselves but configuration descriptors. They rely on the underlying system to parse the
Exec line and spawn the process. Therefore, understanding how the system interprets this line is crucial for debugging launch failures. For more context on managing user groups for desktop applications, you might find
Primary User Group for Linux Desktop Applications useful for understanding permission contexts.
Correcting the Exec Line
The most frequent cause of launch failure is an incorrectly formatted
Exec line. A common mistake is wrapping the command in
bash -c or similar shell wrappers unnecessarily. While sometimes required for complex chaining, it is often incorrect and can lead to environment variable issues or broken paths. The standard approach is to specify the executable directly.
If you need to pass arguments, they should be placed after the executable path. Use placeholders like
%f,
%F,
%u, or
%U if your application supports opening files or URLs directly from the launcher. For example:
Exec=/usr/bin/myapp --flag %f
Avoid using
sh -c unless absolutely necessary for legacy compatibility. Modern applications should invoke their binary directly. If the application is located in a non-standard directory, use the full absolute path. Relative paths are generally not supported in the
Exec line because the working directory may vary depending on where the launcher was invoked.
If your application requires setting environment variables before starting, do not embed them in the
Exec line using export statements. Instead, create a small wrapper script or use the
Environment key if supported by your version of GTK/Qt, though direct execution remains the most robust method.
Permissions and File Location
Even with a perfect syntax, desktop files will not appear if they lack the correct permissions or are stored in the wrong location. System-wide desktop files should reside in
/usr/share/applications/ or
/usr/local/share/applications/. User-specific desktop files belong in
~/.local/share/applications/.
The file must have read permissions for all users. Typically, this means a permission mode of
644 (owner read/write, group and others read). It does not need to be executable itself; the system reads it as text. However, the application binary it references must be executable.
To verify permissions, use the following command:
chmod 644 ~/.local/share/applications/myapp.desktop
After modifying a desktop file, GNOME’s cache may need to be refreshed. In many modern distributions, simply logging out and back in is sufficient. Alternatively, you can run
gtk-update-icon-cache if icons are not updating, although this is less common for general launch issues.
Troubleshooting Common Issues
When an application fails to launch, check the terminal output first. Run the command from the
Exec line manually in a terminal to see error messages. If the binary cannot be found, check the path. If libraries are missing, install them via your package manager.
Another common issue is the
NoDisplay=true key. Ensure this is either absent or set to
false. If it is true, the application will not show up in the GUI launcher, though it may still run from the command line.
Check for hidden characters or encoding issues. Save the file as UTF-8 without BOM. Windows-style line endings (CRLF) can sometimes cause parsing errors in strict environments. Use a Unix-compliant editor to ensure clean formatting.
For issues related to service enabling or systemd integration, which might overlap with desktop scripts, refer to
Failed to Enable Unit: Invalid Argument systemd-enable.service - Desktop Script Issue for deeper diagnostic steps.
Frequently Asked Questions
Why does my application not appear in the GNOME Activities overview?
The most likely reason is that the desktop file lacks the
Categories key or has
NoDisplay=true. Ensure you have included valid categories like
Utility; or
Development; followed by a semicolon. Also, verify the file is in
~/.local/share/applications/ and has
644 permissions.
Can I use relative paths in the Exec line?
No, relative paths are unreliable because the working directory changes when launching from different contexts. Always use absolute paths for both the executable and any data files referenced within the command. If you must use relative logic, create a wrapper script in
/usr/local/bin/ that sets the correct path and calls the main binary.
How do I update the icon cache if the new icon doesn't show?
Run
gtk-update-icon-cache /usr/share/icons/hicolor or the specific theme directory. For user-level icons, ensure the icon file is in the correct subdirectory under
~/.local/share/icons/. Restarting the session usually forces GNOME to re-read the desktop file and refresh the associated icon.
What is the difference between %f and %F in the Exec line?
%f represents a single file name, while
%F represents a list of file names. Use
%f for applications that handle one file at a time, and
%F for those that can open multiple files simultaneously. Using the wrong placeholder may cause the application to ignore additional files selected in the file manager.
Is it safe to edit files in /usr/share/applications/?
It is generally safer to create custom desktop files in
~/.local/share/applications/. Editing system files in
/usr/share/applications/ can be overwritten during package updates. If you must modify a system file, consider creating a copy in the user directory with the same filename, which will take precedence over the system default.