↑ arvau

ArchWiki / XDG Base Directory

de:XDG-Verzeichnisse#Base_Directorys ja:XDG Base Directory pt:XDG Base Directory zh-hans:XDG 基本目录

This article summarizes the XDG Base Directory specification in #Specification and tracks software support in #Support.

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(8). It is up to the user to explicitly define the other variables according to the specification. Changing it might cause issues with pipewire and screen sharing on chromium.

See Environment variables#Globally for information on defining variables.

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.

$HOME/.local/bin

  • Commonly used for user-specific executable files

Note: there is NO $XDG_BIN_HOME directory

  • $HOME/.local is intended to be analogous to /usr/local

  • Note: Since $HOME might be shared between systems of different architectures, installing compiled binaries to $HOME/.local/bin could cause problems when used on systems of differing architectures. This is often not a problem, but the fact that $HOME becomes partially architecture-specific if compiled binaries are placed in it should be kept in mind.

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.

Support

This section exists to catalog the growing set of software using the XDG Base Directory Specification introduced in 2003. This is here to demonstrate the viability of this specification by listing commonly found dotfiles and their support status. For those not currently supporting the Base Directory Specification, workarounds will be demonstrated to emulate it instead.

The workarounds will be limited to anything not involving patching the source, executing code stored in environment variables or compile-time options. The rationale for this is that configurations should be portable across systems and having compile-time options prevent that.

Hopefully this will provide a source of information about exactly what certain kinds of dotfiles are and where they come from.

Contributing

When contributing make sure to use the correct section.

Nothing should require code evaluation, patches or compile-time options to gain support and anything which does must be deemed hardcoded. Additionally, if the process is error prone or difficult, it should also be classified as hardcoded.

  • The first column should be either a link to an internal article, a Template:Pkg or a Template:AUR.

  • The second column is for any legacy files and directories the project had (one per line), this is done so people can find them even if they are no longer read.

  • In the third, try to find the commit or version a project switched to XDG Base Directory or any open discussions and include them in the next two columns (two per line).

  • The last column should include any appropriate workarounds or solutions. Please verify that your solution is correct and functional.

Supported

Partial

Hardcoded

Tools

The tool xdg-ninja detects unwanted files/directories in $HOME which can be moved to XDG base directories. See README for examples.

The tool boxxy can be used to wrap applications which do not respect the XDG base directories and redirect any unwanted files.

The tool ephemeral can be used to link chromium/electron caches that normally live in XDG_CONFIG_HOME to locations in XDG_CACHE_HOME.

Libraries

  1. C

  2. libXDGdirs

  3. libxdg-basedir

  4. C99: Cloudef's simple implementation.

  5. C#

  6. Xdg.Directories

  7. C++

  8. xdg-utils-cxx

  9. xdgpp

  10. Go

  11. adrg/xdg

  12. go-appdir (deprecated, archived)

  13. configdir (deprecated, abandoned)

  14. kyoh86/xdg (deprecated, archived)

  15. Haskell

  16. Officially in directory since 1.2.3.0 ab9d0810ce.

  17. xdg-basedir

  18. JVM: Java, Kotlin, Clojure, Scala, ...

  19. directories-jvm

  20. Perl

  21. File-BaseDir (old spec 0.6)

  22. File-XDG

  23. Python

  24. pyxdg

  25. appdirs (abandoned)

  26. platformdirs

  27. Ruby

  28. bkuhlmann/xdg

  29. rubyworks/xdg (deprecated, abandoned)

  30. Rust

  31. directories-rs

  32. rust-xdg

  33. Swift

  34. swift-xdg

  35. Vala

  36. Builtin support via GLib.Environment.

  37. See get_user_cache_dir, get_user_data_dir, get_user_config_dir, etc.

Tips and tricks

Hiding unwanted directories

For directories which cannot be relocated, some desktop environments such as KDE allow you to hide them:

$ echo path >> ~/.hidden

path is the path of the file/directory, relative to the parent directory of .hidden.

See also