xdg-utils - ArchWiki

Jump to content

xdg-utils provides the official utilities for managing XDG MIME Applications.

- xdg-desktop-menu(1) - Install desktop menu items
- xdg-desktop-icon(1) - copies desktop entries to the user's desktop
- xdg-email(1) - Compose a new email in the user's preferred email client, potentially with subject and other info filled in
- xdg-icon-resource(1) - Install icon resources
- xdg-mime(1) - Query and install MIME types and associations
- xdg-open(1) - Open a file or URI in the user's preferred application
- xdg-screensaver(1) - Enable, disable, or suspend the screensaver
- xdg-settings(1) - Get or set the default web browser and URL handlers

## Installation

Install the xdg-utils package.

## Usage

### Environment variables

Note: A normally functioning desktop environment should automatically set these variables. This section is only necessary for understanding how xdg-utils works, i.e. for troubleshooting purposes.

xdg-utils attempts to integrate with your desktop environment by invoking the specialized programs it provides, where applicable. The evaluation of the current environment is as follows [1]:

- If the standardized XDG_CURRENT_DESKTOP environment variable is set to a recognized desktop environment, the corresponding value is used.
- If any classic fallbacks or environment-specific variables, such as KDE's `KDE_FULL_SESSION`, are present, then the corresponding value is used.
- If the legacy DESKTOP_SESSION environment variable is set to a recognized desktop environment, the corresponding value is used.

During this process, if any match is found, the DE variable is internally overwritten with the detected desktop environment's normalized value. Hence, `DE` is both a legacy environment variable, and an internal state variable for xdg-utils. As an example, if `XDG_CURRENT_DESKTOP` is `KDE`, xdg-utils will internally set `DE` to `kde`. If no match is found, then any pre-existing `DE` value will be used, in such a way that `XDG_CURRENT_DESKTOP=KDE` is equivalent to `XDG_CURRENT_DESKTOP` being unset, and having `DE=kde`. This implementation detail is worth noting because it has the consequence that a pre-set `DE` is ignored if a desktop environment is otherwise detected.

Values of the variables that xdg-utils recognizes are:

Desktop Environment | `XDG_CURRENT_DESKTOP` | `DE` | `DESKTOP_SESSION`
--- | --- | --- | ---
– | `X-Generic`1 | `generic` | –
Cinnamon | `Cinnamon`, `X-Cinnamon` | `cinnamon` | –
Deepin | `Deepin`, `DEEPIN`, `deepin`1 | `deepin` | –
Enlightenment | `ENLIGHTENMENT`1 | `enlightenment` | –
GNOME | `GNOME`2 | `gnome` | `gnome`
GNOME Flashback | `GNOME-Flashback`, `GNOME-Flashback:GNOME`2 | `gnome` | `gnome`
KDE Plasma | `KDE` | `kde` | –
LXDE | `LXDE` | `lxde` | `LXDE`
LXQt | `LXQt` | `lxqt` | –
MATE | `MATE` | `mate` | `mate`
Xfce | `XFCE` | `xfce` | `xfce`, `xfce4`, `Xfce Session`

1. This is not an environment registered with freedesktop.org.
2. GNOME variations, including the GNOME Classic mode, are all regarded as the same by xdg-utils.

Note that this is only a list of what the scripts provided by xdg-utils are capable of detecting. The scripts will still perform generic, environment-agnostic actions under the following conditions:

- The generic routine was asked for, via `XDG_CURRENT_DESKTOP=X-Generic` or `DE=generic`.
- Environment detection failed. All relevant environment variables were unrecognized or unset, and the classic fallbacks did not reveal anything.
- Environment-specific actions were performed, but failed, e.g. due to a missing program.

### xdg-mime

xdg-mime(1) is a script for directly querying and modifying default MIME applications. It is used within other scripts, such as xdg-open, and is also a useful troubleshooting tool.

Determine a file's MIME type:

    $ xdg-mime query filetype photo.jpeg
    image/jpeg

Determine the default application for a MIME type:

    $ xdg-mime query default image/jpeg
    gimp.desktop

Change the default application for a MIME type:

    $ xdg-mime default feh.desktop image/jpeg

Debug default application for MIME type:

    $ env XDG_UTILS_DEBUG_LEVEL=10  xdg-mime query default text/html
    Checking /home/user/.config/mimeapps.list
    Checking /home/user/.local/share/applications/defaults.list and /home/user/.local/share/applications/mimeinfo.cache
    Checking /usr/local/share/applications/defaults.list and /usr/local/share/applications/mimeinfo.cache
    Checking /usr/share/applications/defaults.list and /usr/share/applications/mimeinfo.cache
    qutebrowser.desktop

When it is necessary to determine the MIME type of a file, xdg-mime attempts to use the right program for the desktop environment:

Desktop Environment | Program | Package
--- | --- | ---
Cinnamon | `gio` | glib2
GNOME
GNOME Flashback
LXDE
MATE
Xfce
Deepin | – | –
Enlightenment
LXQt
KDE Plasma | `kmimetypefinder` | kde-cli-tools

In the generic case, xdg-mime will:

- Delegate to mimetype if present. Requires the perl-file-mimeinfo package to be installed.
- Delegate to file if present.

### xdg-open

xdg-open(1) is a resource opener used by many applications, implementing the XDG MIME Applications standard while integrating with the system's desktop environment as much as possible.

If a desktop environment was detected, its provided handler will be invoked [2]:

Desktop Environment | Program | Package
--- | --- | ---
Cinnamon | `gio` | glib2
GNOME
GNOME Flashback
MATE
Deepin | `dde-open` | deepin-api
Enlightenment | `enlightenment_open` | enlightenment
KDE Plasma | `kde-open`1 | kde-cli-tools
LXDE | `pcmanfm` | pcmanfm
LXQt | – | –
Xfce | `exo-open`2 | exo

1. If `KDE_SESSION_VERSION` is unset, then `kfmclient` from konqueror will be used instead. KDE Plasma should set this variable under any condition, though.
2. `gio` from glib2 will also be tried.

In the generic case, xdg-open will:

- Query #xdg-mime for the default desktop entry associated with the resource, parse the desktop entry, and execute its command.
- Delegate to run-mailcap if present. Requires the run-mailcapAUR package to be installed.
- Delegate to mimeopen if present. Requires the perl-file-mimeinfo package to be installed.

Tip: To see which backend xdg-open will use, set `XDG_UTILS_DEBUG_LEVEL=3`.

Since xdg-mime relies on perl-file-mimeinfo package to implement the XDG MIME Applications standard, if you are not using a desktop environment, you should either install perl-file-mimeinfo, or consider a different resource opener.

### xdg-settings

See xdg-settings(1).

Shortcut to open all web MIME types with a single application:

    $ xdg-settings set default-web-browser firefox.desktop

Shortcut for setting the default application for a URL scheme:

    $ xdg-settings set default-url-scheme-handler irc xchat.desktop

## Tips and Tricks

### URL scheme handlers

To set the default application for a URL scheme you may also need to change the default application for the `x-scheme-handler/*` MIME types:

    $ xdg-mime default firefox.desktop x-scheme-handler/https x-scheme-handler/http

Category:

- Freedesktop.org