XDG user directories

From ArchWiki
Revision as of 22:53, 13 January 2019 by C0rn3j (talk | contribs) (→‎Creating default directories: - The package also has a service which was not mentioned there. DEs like GNOME enable it globally, so recommend to do the same in here.)
Jump to navigation Jump to search

From freedesktop.org:

xdg-user-dirs is a tool to help manage "well known" user directories like the desktop folder and the music folder. It also handles localization (i.e. translation) of the filenames.
The way it works is that xdg-user-dirs-update(1) is run very early in the login phase. This program reads a configuration file, and a set of default directories. It then creates localized versions of these directories in the users home directory and sets up a config file in $XDG_CONFIG_HOME/user-dirs.dirs (XDG_CONFIG_HOME defaults to ~/.config) that applications can read to find these directories.

Most file managers indicate XDG user directories with special icons.

Creating default directories

Creating a full suite of localized default user directories within the $HOME directory can be done automatically using xdg-user-dirs and running:

$ xdg-user-dirs-update
Tip: To force the creation of English-named directories, LC_ALL=C xdg-user-dirs-update 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.

xdg-user-dirs provides a user service xdg-user-dirs-update.service, which simply calls $ xdg-user-dirs-update. You should enable that service globally, to ensure the entries remain up to date for every user:

# systemctl enable --global xdg-user-dirs-update.service

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 will/may likely look like this (these are all the template directories):


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