xdg-utils is a set of tools that allows applications to easily integrate with the desktop environment of the user, regardless of the specific desktop environment that the user runs.

About half of the tools focus on tasks commonly required during the installation of a desktop application and the other half focuses on integration with the desktop environment while the application is running.


Included utilities

Each utility's name is linked to its manual page.

  • xdg-desktop-menu - Install desktop menu items
  • xdg-desktop-icon - Install icons on the user's desktop
  • xdg-email - Compose a new email in the user's preferred email client, potentially with subject and other info filled in
  • xdg-icon-resource - Install icon resources
  • xdg-mime - Query and install MIME types and associations
  • xdg-open - Open a URL in the user's preferred application that handles the respective URL or file type
  • xdg-screensaver - Enable, disable, or suspend the screensaver
  • xdg-settings - Get or set the default web browser and URL handlers

Using xdg-utils

Although we expect that these scripts will generally come as part of the operating system, we recommend that you package the scripts that your application needs along with your product as a fallback.

We recommend that you place these scripts in a directory, and then add that directory to the end of the $PATH. So, let's say that you're writing your post installation script, and you want to create a menu item on any XDG compliant environment. Let's further assume that you've just installed to $INSTALL_DIR, and that your desktop file is in $INSTALL_DIR/mycompany-myapp.desktop. Finally, let's say that you've included the xdg-utils package in your installation in $INSTALL_DIR/xdg-utils.

Then a simple post install script could look like this:

export PATH=$PATH:$INSTALL_DIR/xdg-utils/scripts
xdg-desktop-menu install $INSTALL_DIR/mycompany-myapp.desktop

And now your product has a menu item on any XDG compliant desktop!

Note that we strongly recommend using this method - that is, putting your copy of the xdg-utils at the end of the path, and then invoking them without a specific path name. That will allow your users and their system providers to use custom versions of the xdg-utils to adjust for system specific differences.

If you wish to absolutely force the issue and only use the versions you shipped, you could instead hard code the path to the version you bundle with your application. We strongly recommend against this, as it will make your product obsolete more quickly than is necessary.

Relevant specifications