XDG Base Directory Specification

XDG stands for X Desktop Group, a project to work on interoperability for free-software desktop environments for the X Window System (X11) and Wayland on Linux and other Unix-like operating systems. It eventually evolved into freedesktop.org. freedesktop.org produces specifications for interoperability, but it is not a formal standards body. Projects are not required to implement the specifications and there is no certification.

The XDG Base Directory Specification specifies a set of environment variables and configuration files that specify locations that user programs should use to write specific data types, such as configuration files, cache files, runtime files and user data like documents, music, images and so on. The specification also defines default values for unset environment variables and unset configuration values.

Linux distributions usually provide a system-wide XDG configuration in /etc/xdg. The system-wide configuration can be overwritten on a per-user basis.

benefits of using XDG directories

To me, the XGD Base Directory Specification is useful in two ways:

• using XDG directories keeps the home directory less cluttered and more organized. You don’t end up with dozens of dotfiles and config directories like .whatever-prog directly in your home dir.
• Organizing your data files in respect of data type helps running your backups faster and keeping your backup files smaller. I don’t find it particularly useful for my backups to include stuff like image thumbnails or my web browsers cache. In case of a data loss, such data is automatically reconstructed on the fly (i.e. image thumbnails) or not of much importance (i.e. a web browser’s cache).

Those two points only apply as far as programs adhere to the XDG Base Directory Specification. I have compiled lists of programs that adhere and do not adhere to the XDG spec.

configuring the XDG directories

There are a bunch of programs to configure XDG and read its configuration (see below programs to manage XDG Base Directories). Personally, I think those programs are a bit of an overkill and I do well without them. The XDG Base Dirs can be configured by simply exporting the respecting environment vars in your .profile. The image below illustrates the concept:

In the upper left hand in the image there is the home directory tree of the (fictional) user alice plus a directory within /tmp, which alice uses for her runtime data that is to be cleaned up periodically.

In the upper right hand is an excerpt of alice’s .profile that contains some XDG Base Directories config vars.

On the lower right hand of the image is the system-wide XDG config file overwritten by the user specific config file in alice’s home dir.

The most straight-forward way to configure the XDG Base Directories:

• export the respective env vars in your .profile.
• additionally, if you use locations that get removed during a shutdown/reboot of your machine (i.e. in /tmp), create those locations before you export the env var.
• edit /etc/xdg/user-dirs.conf and disable xdg-user-dirs-update with enabled=False.

That’s it.

Here is an example of a section in .profile:

For the list of env vars for XDG Base Directories and env vars for user specific data dirs see the sections below.

environment variables

XDG base directories

All environment variables start with XDG_. For most environment variables the specification defines a default that should be used if the variable is not set or empty. The XDG Base Directory spec specifies the following directories:

XDG_RUNTIME_DIR

XDG Base Directory Specification states the following requirements for XDG_RUNTIME_DIR:

• The directory must be owned by the user, with read and write access limited to the user. That is, the Unix access mode must be 0700.
• Files in XDG_RUNTIME_DIR must not survive reboot or a full logout/login cycle.
• XDG_RUNTIME_DIR must be on a local file system that is not shared with any other system.
• XDG_RUNTIME_DIR must be located in a fully featured file system that supports AF_UNIX sockets, symbolic links, hard links, proper permissions, file locking, sparse files, memory mapping, file change notifications, and a reliable hard link count. The file system should not impose any restriction on the file name character set.

It is not clear to me what a full logout/login cycle is. I suspect the meaning full logout/login cycle here is a reboot. The spec states about this:

" The lifetime of the directory MUST be bound to the user being logged in. It MUST be created when the user first logs in and if the user fully logs out the directory MUST be removed. If the user logs in more than once he should get pointed to the same directory, and it is mandatory that the directory continues to exist from his first login to his last logout on the system, and not removed in between. Files in the directory MUST not survive reboot or a full logout/login cycle. "

XDG Base Directory Specification, Environment variables

Files in XDG_RUNTIME_DIR may be subject to periodic clean-up. Modification of file access time timestamp at least once every 6 hours of monotonic time or setting the ‘sticky’ bit on the file prevent the file from being subject to periodic clean-up.

The XDG Base Directory Specification does not specify a default directory for XDG_RUNTIME_DIR:

" If $XDG_RUNTIME_DIR is not set applications should fall back to a replacement directory with similar capabilities and print a warning message. "

XDG Base Directory Specification, Environment variables

user-specific executables

The XDG Base Directory Specification expects user-specific executable files to be located in $HOME/.local/bin. There is no configuration value to specify the location for user-specific executables. All what the spec states about this is:

" There is a single base directory relative to which user-specific executable files may be written. [...] User-specific executable files may be stored in $HOME/.local/bin. Distributions should ensure this directory shows up in the UNIX $PATH environment variable, at an appropriate place. "

env vars for user specific data dirs

The env vars for data dirs in the user’s home dir are not specified in the XDG Base Directory spec. The system-wide config file /etc/xdg/user-dirs.defaults lists the env vars, but without the suffix XDG_ These env vars are, in alphabetical order:

config files

system-wide config files in /etc/xdg

user specific config file

The system-wide config file user-dirs.defaults can be overwritten with a user specific config file user-dirs.dirs. This file has to be located in the dir configured with $XDG_CONFIG_HOME or $XDG_CONFIG_DIRS.

programs to manage XDG Base Directories

To get an overview of the files and programs involved, run man -k xdg which produces an output like shown below (programs for other topics like xdg-screensaver are omitted in the output):

xdg-user-dirs-update

Any configured directories that point to non-existing locations are reset by pointing them to the users home directory. It is assumed that this typically happens when the users removed the directory, because they don’t want to use it anymore.

tips for working with XDG Base dirs

• I do not use the locations for music (what’s the point of having your MP3-collection in your home dir?), videos, pictures, and so on. Thus, I set the respecting env vars inside ${HOME}/files/xdg to move those dirs out of sight. Programs almost never write to those dirs anyway.
• Some Programs write data into XDG_DATA_HOME that is better located in XDG_CACHE_HOME, XDG_CONFIG_HOME or XDG_STATE_HOME. From time to time, I check the dirs in XDG_DATA_HOME to see what got dumped in there and check if I can configure the programs to write to locations like XDG_CONFIG_HOME and so on.

Here is the XDG section in my .profile:

wrapup

The naming inconsistency between /etc/xdg/user-dirs.defaults and user-dirs.dirs (why not user-dirs.conf?), the default value for user-specific executables without a definition for the corresponding env var and the complete absence of all env vars for the user’s data file locations in the XDG Base Directories Specification are quite annoying. Nevertheless, the spec is quite useful and it’s application is straight forward once you have wrapped your head around the spec. For the latter, I hope this article is useful.

reference

freedesktop.org, Specifications