Launch Desktop Applications Reliably with gtk-launch

gtk-launch starts an application by its desktop-file name and hands it one or more URIs. This guide uses gtk-launch from Debian package libgtk-3-bin version 3.24.41-4ubuntu1.3, with GTK version 3.24.41 installed here, and shows how to tell a bad application name apart from a missing display.

Allow about ten minutes. You need a shell and, for an actual launch, a graphical session with a usable display. The inspection and help commands below are ordinary user commands. sudo is not a normal prerequisite: using it will not create a desktop entry or repair a display connection.

1. Confirm the installed command

Check which binary is being used and which GTK build it reports:

$ command -v gtk-launch
/usr/bin/gtk-launch
$ gtk-launch --version
3.24.41

The version output is the useful checkpoint. If the path or version differs, keep that in mind when comparing examples with another machine. Record the package version separately:

$ dpkg-query -W -f='${Package} ${Version}\n' libgtk-3-bin
libgtk-3-bin 3.24.41-4ubuntu1.3

2. Read the command shape

Ask the installed program for its concise help:

$ gtk-launch --help
Usage:
  gtk-launch [OPTION...] APPLICATION [URI...] : launch an APPLICATION

The important part is gtk-launch APPLICATION [URI...]. The first non-option argument is the application name; any following arguments are URIs passed to that application. The name must match an application desktop file, with or without its .desktop suffix.

The local GTK 3.24.41 build also advertises --display=DISPLAY, which selects the X display. The manpage documents --help and --version; treat the installed help as the authority for options available on your particular build.

Checkpoint: do not put a filesystem path in the application position unless that path is also a desktop-file identifier. gtk-launch /usr/bin/firefox is not the same operation as launching Firefox by its desktop entry.

3. Find an exact desktop-file name

Look in the standard application directory and inspect the file name, not only the human-readable Name= field:

$ find /usr/share/applications -maxdepth 1 -type f -name '*.desktop' | sort | head
/usr/share/applications/btop.desktop
/usr/share/applications/display-im6.q16.desktop
/usr/share/applications/htop.desktop
$ sed -n '1,12p' /usr/share/applications/htop.desktop
[Desktop Entry]
Type=Application
Version=1.0
Name=Htop
...
Exec=htop

On another system the list will differ. A desktop file can come from a package, a desktop environment, or an application installed for one user. If a file is absent from /usr/share/applications, check the user application directory ~/.local/share/applications if your desktop environment uses it. Do not guess an identifier from an application window title.

4. Launch one application

Use the exact file name without the suffix. This example starts the installed Htop entry and relies on the default display:

$ gtk-launch htop

The command normally returns no useful text. The application may open in a terminal window because its desktop file says Terminal=true. Close it normally when you have finished: the launch is not a configuration change, so there is no persistent undo operation.

To make the identifier explicit, the suffix is also accepted:

$ gtk-launch htop.desktop

Warning: do not run a desktop file you have not inspected. Its Exec= line controls what is started, and launching it can open a program, a document, or a helper process. This matters especially when testing entries copied into a user application directory.

5. Pass a URI to the application

Put the URI after the application name. The following is a pattern, not a command to paste unchanged: replace APPLICATION_NAME with a desktop-file name you have inspected, and replace the URI with a resource that application is designed to handle:

$ gtk-launch APPLICATION_NAME 'https://example.invalid/document'

Quoting keeps shell punctuation inside one argument. The URI is handed to the launched application; gtk-launch does not promise the application supports that scheme or resource. Multiple URIs can follow the application name:

$ gtk-launch APPLICATION_NAME 'file:///home/USER/one.txt' 'file:///home/USER/two.txt'

Replace USER with the account name and use files the target application can open. A malformed URI, an unsupported scheme, or an application that only accepts one location can fail after the application starts: that is an application-level problem, not proof the desktop lookup failed.

6. Diagnose the two common failures

First distinguish a display failure. Running a graphical launch from a headless shell can produce a GTK warning such as this:

$ gtk-launch htop
(gtk-launch:12345): Gtk-WARNING **: cannot open display:
$ printf 'exit status: %s\n' "$?"
exit status: 1

The process number and surrounding diagnostic vary. Log in to the graphical session, use its display environment, or select the correct X display with the installed build's --display=DISPLAY option. Do not assume sudo fixes this; it can remove or change the display credentials the user session supplied.

Next, test the application name only once a display is available. A name that does not match a desktop file will fail before the intended application is useful. Search the desktop directories again, check spelling and try the optional .desktop suffix. If the entry is in a user directory, check the file is readable and its desktop entry is valid.

Checkpoint: a successful return from gtk-launch means the launch request was accepted. It does not certify the application stayed open, loaded every URI, or completed the requested work. Check the application's own window, logs, or exit status when those outcomes matter.

7. Keep automation predictable

For scripts, check the command status and keep the application name and each URI as separate, quoted shell arguments:

if gtk-launch "$APPLICATION_NAME" "$URI"; then
    printf '%s\n' 'launch request accepted'
else
    printf 'gtk-launch failed for %s\n' "$APPLICATION_NAME" >&2
    exit 1
fi

Set APPLICATION_NAME and URI from trusted, validated values. Do not concatenate untrusted text into a shell command, and do not treat a URI as a command-line option by stripping away its quoting. If a launcher must work without a graphical session, choose a non-GUI service or command designed for that environment instead.

Done means