Launch D-Bus Applications Reliably with gapplication

You will use gapplication to discover desktop applications that advertise D-Bus activation, start one by its application ID, open files or URIs, and inspect its declared actions. The commands are ordinary user commands. They do not install software or require sudo, but launching an application can still create windows, notifications or other user-visible state.

Allow about 10 minutes for a first run. You need a graphical user session with a D-Bus session bus, the gapplication executable, and an application whose desktop entry contains DBusActivatable=true. This guide uses the GLib command installed here, which reports version 2.86.4. The Ubuntu package record on this machine is libglib2.0-bin 2.80.0-6ubuntu3.9, so check the executable you actually run rather than assuming the distribution package version.

Checkpoint 1: confirm the command and version

Start by checking the binary on your PATH. The version subcommand prints the GLib version that supplied it, and the help output lists the supported operations.

command -v gapplication
gapplication version
gapplication help

On this machine the first command prints /home/linuxbrew/.linuxbrew/bin/gapplication, followed by 2.86.4. The available commands are help, version, list-apps, launch, action and list-actions. If the version command fails, stop here and fix the installation or PATH before diagnosing D-Bus.

Checkpoint 2: find a usable application ID

Do not guess an application ID from its visible name. Ask GLib to scan desktop files in the current XDG data directories:

gapplication list-apps

The output is one application ID per line. An ID normally uses reverse-DNS form, such as org.example.viewer, and does not include the .desktop suffix. The command only reports entries that advertise D-Bus activation. It does not prove that the application is installed correctly, that its service is running, or that its D-Bus object implements the required interface.

If the list is unexpectedly empty, check the search path and desktop metadata before changing anything:

printf '%s\n' "$XDG_DATA_DIRS"
rg -l '^DBusActivatable=true' \
  /usr/share/applications /usr/local/share/applications 2>/dev/null

An unset XDG_DATA_DIRS is not automatically an error: GLib applies its standard data-directory defaults. A desktop file in a non-standard location will not be found unless that location is in the relevant XDG data search path. Re-run gapplication list-apps after correcting the environment in the same session.

Launch an application without a file

Pass the application ID without .desktop to launch:

gapplication launch org.example.viewer

Replace the example with an ID from your own list. With no file arguments, the application is activated. Success normally produces no terminal output, so verify it by checking the application window or its own process and logs. The command exits non-zero when activation cannot be sent or the target does not implement the expected D-Bus interface.

Open a file or URI

Additional arguments are passed as files to open. They may be relative or absolute filenames, or URIs:

gapplication launch org.example.viewer /home/you/Pictures/sample.foo
gapplication launch org.example.viewer 'file:///home/you/Pictures/sample.foo'
gapplication launch org.example.viewer /home/you/Pictures/*.foo

The shell expands the wildcard before gapplication sees it. That is useful for a group of matching files, but it can also select more files than intended. Inspect the expansion first when the directory is unfamiliar:

printf '%s\n' /home/you/Pictures/*.foo

Use quoting when a filename contains spaces. The application decides whether it can open the supplied type. gapplication does not convert files, copy them, or provide a recovery command if the application edits or moves them. If an application opens the wrong file, close it through the application before retrying; there is no generic undo operation at the D-Bus launcher level.

Inspect and invoke desktop actions

Desktop actions are named operations declared in the application's .desktop file. List them before invoking one:

gapplication list-actions org.example.viewer

For a declared action, use its action name exactly as listed:

gapplication action org.example.viewer create

An action may accept one optional parameter written as a single GVariant argument. Quote the whole value so the shell does not split it:

gapplication action org.example.viewer show-item '"item_id_828739"'

The quoting has two layers: the outer shell quotes preserve one argument, while the inner double quotes make the value a GVariant string. The parameter type is defined by the application, not by gapplication. If the action expects a different type, read that application's documentation or desktop integration code. Do not add a second parameter: the command accepts at most one optional action parameter.

Connect the command to a desktop file

An application can use gapplication in an Exec line as a compatibility fallback. The desktop entry still needs DBusActivatable=true, an application ID that matches the D-Bus service, and field codes appropriate to the entry:

[Desktop Entry]
Version=1.1
Type=Application
Name=Example Viewer
DBusActivatable=true
MimeType=image/x-example;
Exec=gapplication launch org.example.viewer %F
Actions=create;

[Desktop Action create]
Name=Create a new item
Exec=gapplication action org.example.viewer create

%F means a list of filenames supplied by the desktop environment. The action declaration's name, create, must match the action command. This snippet is a design example, not a complete installable application: the D-Bus service and its org.freedesktop.Application implementation must exist separately. After installing or editing a desktop entry, validate it with the desktop-file tools available on your distribution and start a new desktop session if the environment has cached the old metadata.

Diagnose a failed launch

Work from the least disruptive check to the most active one:

1. Run gapplication version and gapplication list-apps to confirm the executable and discovery path.
2. Read the matching desktop file and confirm DBusActivatable=true, the application ID, and any declared actions agree.
3. Run gapplication list-actions APP-ID. An empty result can be valid when no actions are declared.
4. Try gapplication launch APP-ID without a file, then capture the exact error and exit status.

For example, a desktop entry can be discovered but still fail at activation if its executable is missing or its service does not implement org.freedesktop.Application. That is an application or packaging problem, not a reason to add sudo. Inspect the application's own logs and the session bus environment instead. Keep the original error: messages such as an unknown interface distinguish a bad D-Bus target from a missing application ID.

Done means

• gapplication version prints the GLib version you intended to use.
• gapplication list-apps shows the target application ID.
• You inspected the desktop entry before launching an unfamiliar target.
• A plain launch, file open, or declared action completes with the expected application behaviour.
• Any failure is recorded with its exit status and D-Bus error, without changing system files or using elevated privileges.