knowledge/technology/linux/XDG.md

obj	arch-wiki	rev
concept	https://wiki.archlinux.org/title/XDG_user_directories	2025-01-08

XDG Directories

The XDG User Directories are a standardized way to define and access common user directories in Unix-like operating systems, primarily defined by the XDG Base Directory Specification from the FreeDesktop.org project.

These directories provide users and applications with predefined paths for storing specific types of files, such as documents, downloads, music, and more. By using these directories, applications can integrate better with the operating system's file structure and provide a consistent experience for users.

Creating default directories

Creating a full suite of localized default user directories within the $HOME directory can be done automatically by running:

xdg-user-dirs-update

Tip: To force the creation of English-named directories, LC_ALL=C.UTF-8 xdg-user-dirs-update --force can be used.

When executed, it will also automatically:

• Create a local ~/.config/user-dirs.dirs configuration file: used by applications to find and use home directories specific to an account.
• Create a local ~/.config/user-dirs.locale configuration file: used to set the language according to the locale in use.

The user service xdg-user-dirs-update.service will also be installed and enabled by default, in order to keep your directories up to date by running this command at the beginning of each login session.

Creating custom directories

Both the local ~/.config/user-dirs.dirs and global /etc/xdg/user-dirs.defaults configuration files use the following environmental variable format to point to user directories: XDG_DIRNAME_DIR="$HOME/directory_name" An example configuration file may likely look like this (these are all the template directories):

# ~/.config/user-dirs.dirs

XDG_DESKTOP_DIR="$HOME/Desktop"
XDG_DOCUMENTS_DIR="$HOME/Documents"
XDG_DOWNLOAD_DIR="$HOME/Downloads"
XDG_MUSIC_DIR="$HOME/Music"
XDG_PICTURES_DIR="$HOME/Pictures"
XDG_PUBLICSHARE_DIR="$HOME/Public"
XDG_TEMPLATES_DIR="$HOME/Templates"
XDG_VIDEOS_DIR="$HOME/Videos"

As xdg-user-dirs will source the local configuration file to point to the appropriate user directories, it is therefore possible to specify custom folders. For example, if a custom folder for the XDG_DOWNLOAD_DIR variable has named $HOME/Internet in ~/.config/user-dirs.dirs any application that uses this variable will use this directory.

Note

: Like with many configuration files, local settings override global settings. It will also be necessary to create any new custom directories.

Alternatively, it is also possible to specify custom folders using the command line. For example, the following command will produce the same results as the above configuration file edit:

xdg-user-dirs-update --set DOWNLOAD ~/Internet

Querying configured directories

Once set, any user directory can be viewed with xdg-user-dirs. For example, the following command will show the location of the Templates directory, which of course corresponds to the XDG_TEMPLATES_DIR variable in the local configuration file:

xdg-user-dir TEMPLATES

Specification

Please read the full specification. This section will attempt to break down the essence of what it tries to achieve.

Only XDG_RUNTIME_DIR is set by default through pam_systemd. It is up to the user to explicitly define the other variables according to the specification.

User directories

• XDG_CONFIG_HOME: Where user-specific configurations should be written (analogous to /etc). Should default to $HOME/.config.
• XDG_CACHE_HOME: Where user-specific non-essential (cached) data should be written (analogous to /var/cache). Should default to $HOME/.cache.
• XDG_DATA_HOME: Where user-specific data files should be written (analogous to /usr/share). Should default to $HOME/.local/share.
• XDG_STATE_HOME: Where user-specific state files should be written (analogous to /var/lib). Should default to $HOME/.local/state.
• XDG_RUNTIME_DIR: Used for non-essential, user-specific data files such as sockets, named pipes, etc. Not required to have a default value; warnings should be issued if not set or equivalents provided. Must be owned by the user with an access mode of 0700. Filesystem fully featured by standards of OS. Must be on the local filesystem. May be subject to periodic cleanup. Modified every 6 hours or set sticky bit if persistence is desired. Can only exist for the duration of the user's login. Should not store large files as it may be mounted as a tmpfs.pam_systemd sets this to /run/user/$UID.

System directories

• XDG_DATA_DIRS: List of directories separated by : (analogous to PATH). Should default to /usr/local/share:/usr/share.
• XDG_CONFIG_DIRS: List of directories separated by : (analogous to PATH). Should default to /etc/xdg.