Put a Desktop Launcher on Your Linux Desktop with xdg-desktop-icon

You will install a .desktop launcher on the current user's desktop, verify the copied file, and remove it cleanly if you change your mind. The examples use xdg-desktop-icon 1.1.3 from xdg-utils 1.1.3-4.1ubuntu3.

Allow about ten minutes. You need a shell, a readable launcher file, and a desktop directory that your session can use. This guide changes files in your desktop folder, so do not run the examples against an important launcher until you have checked the source and destination names.

1. Check the installed command

Confirm which executable will run and record its version. These are read-only commands:

$ command -v xdg-desktop-icon
/usr/bin/xdg-desktop-icon
$ xdg-desktop-icon --version
xdg-desktop-icon 1.1.3

The interface is deliberately small:

xdg-desktop-icon install [--novendor] FILE
xdg-desktop-icon uninstall FILE

install copies a file to the current user's desktop. It accepts a .desktop launcher or another file, such as a README. uninstall removes the file with the same basename from the desktop location. The command chooses that location from the desktop session where possible, falling back to $HOME/Desktop in the installed 1.1.3 script.

2. Create a launcher with a safe filename

A launcher is an INI-style text file whose first section is [Desktop Entry]. For this example, save the following as acme-report.desktop in your current directory:

[Desktop Entry]
Type=Application
Name=Acme Report
GenericName=Report viewer
Comment=Open the Acme report viewer
Exec=/usr/local/bin/acme-report
Icon=acme-report

Replace the Exec path with a real executable and adjust the name and icon. An icon value can be an icon name from the active theme or an absolute image path. If the program opens files, the desktop-entry format supports placeholders such as %f; use the placeholder appropriate for the program rather than guessing.

The filename matters before the command reads the file. By default, xdg-desktop-icon requires a .desktop filename to start with an alphabetic vendor prefix followed by a dash. acme-report.desktop passes that check. Names such as report.desktop and 123-report.desktop do not.

$ sed -n '1,20p' ./acme-report.desktop
$ test -x /usr/local/bin/acme-report && echo 'Exec target is executable'
Exec target is executable

3. Install the launcher

Run this as your normal user:

$ xdg-desktop-icon install ./acme-report.desktop
$ printf 'exit status: %s\n' "$?"
exit status: 0

Success is normally silent. The command copies the source using its basename and makes the installed copy executable for the owner. A zero exit status means the action completed, not that the launcher will start successfully. The desktop environment may also need to refresh its view before the icon appears.

Find the installed copy without assuming a particular desktop path:

$ find "$HOME/Desktop" -maxdepth 1 -type f -name 'acme-report.desktop' -print
/home/you/Desktop/acme-report.desktop

If your session uses a different desktop directory, ask the XDG user-directory tool when it is available:

$ xdg-user-dir DESKTOP
/home/you/Desktop

Use the path printed on your machine. Do not infer it from another user's account or copy the example output literally.

4. Test the launcher and separate the likely failures

Open the launcher from your desktop, or invoke the Exec program directly in a terminal. If the launcher does nothing, check these in order:

• the installed file has the expected contents and basename;
• the Exec path exists and is executable;
• the command line does not depend on shell syntax that desktop entries do not interpret as a shell;
• the icon name exists in the current theme, or the absolute icon path is readable.

For a launcher that accepts dropped files, test the program with a real sample before adding %f or %F. For URLs, the desktop-entry placeholders are %u and %U. These are arguments supplied by the desktop environment, not environment-variable expansions.

5. Undo the installation

$ xdg-desktop-icon uninstall ./acme-report.desktop
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ test ! -e "$HOME/Desktop/acme-report.desktop" && echo 'launcher removed'
launcher removed

The uninstall argument is used to obtain the basename, so it need not point at the original source file. If the desktop file was copied to a session-specific directory, verify that location with xdg-user-dir DESKTOP and inspect it directly. Keep the source file if you may want to reinstall the launcher later.

Common errors and the deliberate override

An exit status of 1 indicates command-line syntax or the vendor-prefix check. Status 2 means an input file passed to install did not exist. Status 4 means the desktop action failed, and status 5 means the input could not be read. A missing helper tool or permission to write the destination can produce other non-zero failures; run with XDG_UTILS_DEBUG_LEVEL=1 to request diagnostic output on standard error.

If you control the filename and intentionally do not want a vendor prefix, use the narrow override:

$ xdg-desktop-icon install --novendor ./report.desktop

--novendor disables only the filename check. It does not validate the desktop-entry contents, make an invalid Exec command work, or grant permission to write the destination. Prefer a vendor-prefixed name when you can, because the prefix reduces launcher name collisions.