XDG User Directories

Some Linux distro desktop environments use the xdg-user-dirs tool to manage user directories. It creates default directories and handle localization of the filenames.

Early in the login phase, xdg-user-dirs-update is run, which reads a configuration file (/etc/xdg/user-dirs.conf), and a set of default directories (/etc/xdg/user-dirs.defaults). It then creates localized versions of a set of default directories in the user’s home directory, and sets up a configuration file in $XDG_CONFIG_HOME/user-dirs.dirs (XDG_CONFIG_HOME defaults to ~/.config). Applications can then use these directory variables as default location for files.

Creating default directories

When xdg-user-dirs-update is executed, it will:

• Create a local ~/.config/user-dirs.dirs configuration file.
• Create a local ~/.config/user-dirs.locale configuration file used to set the default language locale
• Enable the user service xdg-user-dirs-update.service by default, in order to keep user directories up to date by re-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 format

XDG_<directory_name>_DIR="$HOME/<directory_name>"

for example:

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

It is therefore possible to specify custom folders. For example,

XDG_MUSIC_DIR="$HOME/Documents/Music"
XDG_PICTURES_DIR="$HOME/Documents/Pictures"
XDG_VIDEOS_DIR="$HOME/Documents/Videos"
XDG_DOWNLOAD_DIR="$HOME/temp"

Alternatively, it is also possible to specify custom folders using command line. For example, the following command will set the DOWNLOAD folder in the local configuration file.

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

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 Download directory (which corresponds to the XDG_DOWNLOAD_DIR variable in the local configuration file:

xdg-user-dir DOWNLOAD

Disable XDG user directory management

Edit the global configuration file (/etc/xdg/user-dirs.conf), and change enabled=True to enabled=False.

To enable/disable XDG for a single user, copy the configuration file to ~/.config/user-dirs.conf, and set the enable option accordingly.