XDG Base Directory

From ArchWiki
Revision as of 18:29, 3 February 2017 by Earnest (talk | contribs) (Hardcoded: Add current discussion for Idris PR)
Jump to navigation Jump to search

This article 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.

XDG Base Directory 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, using absolute paths that point to existing directories.

User directories

    • Where user-specific configurations should be written (analogous to /etc).
    • Should default to $HOME/.config.
    • Where user-specific non-essential (cached) data should be written (analogous to /var/cache).
    • Should default to $HOME/.cache.
    • Where user-specific data files should be written (analogous to /usr/share).
    • Should default to $HOME/.local/share.
    • 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.

System directories

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


When contributing make sure to use the correct section.

Nothing should require code evaluation (such as vim and VIMINIT), patches or compile-time options to gain support and anything which does must be deemed hardcoded. Additionally if the process is too error prone or difficult, such as Haskell's cabal or eclipse, they should also be considered as hardcoded.

  • The first column should be the project name, ideally the command name if it is not ambigious, linked to their website or an appropriate internal wiki article.
  • 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.
  • Finally the fourth should include any appropriate workarounds or solutions for unsupported projects. Be terse, this article assumes intelligence and good charity from the reader. If something is unclear then feel free to expend some explanation to clarify it.

Lastly, and this goes without saying, please verify that your solution is correct and functional.


Application Legacy Path Supported Since Discussion Notes
antimicro ~/.antimicro [1] [2]
aria2 ~/.aria2 [3] [4]
blender ~/.blender [5] [6]
burp [7]
chromium ~/.chromium [8] [9] [10]
citra ~/.citra-emu [11] [12]
cower [13]
d-feet ~/.d-feet [14]
dolphin-emu ~/.dolphin-emu [15] [16]
dunst [17] [18]
fontconfig ~/.fontconfig


[19] Use "$XDG_DATA_HOME"/fonts to store fonts instead.
fontforge ~/.FontForge


[20] [21] [22]
freerdp ~/.freerdp [23]
gconf ~/.gconf [24] [25]
git ~/.gitconfig [26]
gstreamer-1.0 [27] [28]
htop ~/.htoprc [29]
i3 ~/.i3 [30]
i3status ~/.i3status.conf [31]
inkscape ~/.inkscape 0.47 [32]
latexmk ~/.latexmkrc
lftp ~/.lftp [33] [34]
lgogdownloader ~/.gogdownloader [35] [36]
LibreOffice [37] [38] [39]
livestreamer ~/.livestreamerrc [40] [41]
llpp [42] Currently llpp places the configuration directly under XDG_CONFIG_HOME instead of creating a directory.
mc ~/.mc [43] [44] [45] [46]
milkytracker ~/.milkytracker_config [47] [48]
mintty ~/.minttyrc 2.3.7 [49]
mpd ~/.mpdconf [50]
mpv ~/.mpv [51] [52]
mutt ~/.mutt [53] [54]
mypaint ~/.mypaint [55]
ncmpcpp ~/.ncmpcpp [56] [57] [58] [59] ncmpcpp_directory should be set to avoid an error.log file in ~/.ncmpcpp.
neovim ~/.nvim



[60] [61] [62]
newsbeuter ~/.newsbeuter [63] [64] It is required to create both directories [65]:

$ mkdir -p "$XDG_DATA_HOME"/newsbeuter "$XDG_CONFIG_HOME"/newsbeuter

OfflineIMAP ~/.offlineimaprc [66] [67]
opentyrian ~/.opentyrian [68] [69]
pcsx2 ~/.pcsx2 [70] [71] [72] [73] [74] [75]
ppsspp ~/.ppsspp [76] [77]
procps-ng ~/.toprc [78] [79] [80]
pacman ~/.makepkg.conf [81] [82]
PulseAudio ~/.pulse



[84] [85] [86]

qtile [88] [89] [90] [91] Some optional bar widgets can create files and directories in non-compliant paths, but most often these are still configurable.
rr ~/.rr [92] [93]
surfraw ~/.surfraw.conf


[94] [95] [96]
sway ~/.sway/config [97] [98]
transmission ~/.transmission [99] [100]
util-linux [101]
uzbl [102] [103]
VirtualBox ~/.VirtualBox 4.3 [104]
VLC media player ~/.vlcrc [105] [106]
warsow ~/.warsow-2.x [107] [108]
wireshark ~/.wireshark [109]
xsettingsd ~/.xsettingsd [110]


Application Legacy Path Supported Since Discussion Notes
abook ~/.abook $ abook --config "$XDG_CONFIG_HOME"/abook/abookrc \

--datafile "$XDG_CACHE_HOME"/abook/addressbook

Anki ~/Anki


[111] [112] $ anki -b "$XDG_DATA_HOME"/Anki
aspell ~/.aspell.conf
Atom ~/.atom $ export ATOM_HOME="$XDG_DATA_HOME"/atom
cargo ~/.cargo [113] [114] $ export CARGO_HOME="$XDG_DATA_HOME"/cargo
ccache ~/.ccache $ export CCACHE_DIR="$XDG_CACHE_HOME"/ccache
ChezScheme ~/.chezscheme_history $ petite --eehistory "$XDG_DATA_HOME"/chezscheme/history
composer ~/.composer $ export COMPOSER_HOME="$XDG_CONFIG_HOME"/composer


conky ~/.conkyrc [115] [116] $ conky --config="$XDG_CONFIG_HOME"/conky/conkyrc
coreutils ~/.dircolors $ source "$(dircolors "$XDG_CONFIG_HOME"/dircolors)"
crawl ~/.crawl Trailing '/' is required:

$ export CRAWL_DIR="$XDG_DATA_HOME"/crawl/

dict ~/.dictrc $ dict -c "$XDG_CONFIG_HOME"/dict/dictrc
ELinks ~/.elinks $ export ELINKS_CONFDIR="$XDG_CONFIG_HOME"/elinks
emscripten ~/.emscripten




3624 $ export EM_CONFIG="$XDG_CONFIG_HOME"/emscripten/config

$ export EM_CACHE="$XDG_CACHE_HOME"/emscripten/cache

$ export EM_PORTS="$XDG_DATA_HOME"/emscripten/cache

$ emcc --em-config "$XDG_CONFIG_HOME"/emscripten/config \ --em-cache "$XDG_CACHE_HOME"/emscripten/cache

gdb ~/.gdbinit $ gdb -nh -x "$XDG_CONFIG_HOME"/gdb/init
get_iplayer ~/.get_iplayer $ export GETIPLAYERUSERPREFS="$XDG_DATA_HOME"/get_iplayer
GIMP ~/.gimp-2.8


[117] [118] [119] $ export GIMP2_DIRECTORY="$XDG_CONFIG_HOME"/gimp
gliv ~/.glivrc $ gliv --glivrc="$XDG_CONFIG_HOME"/gliv/glivrc
GnuPG ~/.gnupg [120] [121] $ export GNUPGHOME="$XDG_CONFIG_HOME"/gnupg

$ gpg2 --homedir "$XDG_CONFIG_HOME"/gnupg

Google Earth ~/.googleearth Some paths can be changed with the KMLPath and CachePath options in ~/.config/Google/GoogleEarthPlus.conf
gtk ~/.gtkrc $ export GTK_RC_FILES="$XDG_CONFIG_HOME"/gtk-1.0/gtkrc
gtk2 ~/.gtkrc-2.0 $ export GTK2_RC_FILES="$XDG_CONFIG_HOME"/gtk-2.0/gtkrc
httpie ~/.httpie [122] $ export HTTPIE_CONFIG_DIR="$XDG_CONFIG_HOME"/httpie
ipython/jupyter ~/.ipython $ export IPYTHONDIR="$XDG_CONFIG_HOME"/jupyter


irssi ~/.irssi [123] $ irssi --config="$XDG_CONFIG_HOME"/irssi/config \


isync ~/.mbsyncrc $ mbsync -c "$XDG_CONFIG_HOME"/isync/mbsyncrc
less ~/.lesshst $ mkdir -p "$XDG_CACHE_HOME"/less

$ export LESSHISTFILE="$XDG_CACHE_HOME"/less/history

$ export LESSHISTFILE=- can be used to disable this feature.

$ export LESSKEY="$XDG_CONFIG_HOME"/less/lesskey

libdvdcss ~/.dvdcss [124] $ export DVDCSS_CACHE="$XDG_DATA_HOME"/dvdcss
libice ~/.ICEauthority [125] $ export ICEAUTHORITY="$XDG_RUNTIME_DIR"/ICEauthority
libx11 ~/.XCompose $ export XCOMPOSEFILE="$XDG_CONFIG_HOME"/X11/xcompose
ltrace ~/.ltrace.conf $ ltrace -F "$XDG_CONFIG_HOME"/ltrace/ltrace.conf
Mathematica ~/.Mathematica $ export MATHEMATICA_USERBASE="$XDG_CONFIG_HOME"/mathematica
mednafen ~/.mednafen $ export MEDNAFEN_HOME="$XDG_CONFIG_HOME"/mednafen
moc ~/.moc $ mocp -M "$XDG_CONFIG_HOME"/moc

$ mocp -O MOCDir="$XDG_CONFIG_HOME"/moc

MPlayer ~/.mplayer $ export MPLAYER_HOME="$XDG_CONFIG_HOME"/mplayer
ncurses ~/.terminfo Precludes system path searching:

$ export TERMINFO="$XDG_DATA_HOME"/terminfo

$ export TERMINFO_DIRS="$XDG_DATA_HOME"/terminfo:/usr/share/terminfo

notmuch ~/.notmuch-config [126] $ export NOTMUCH_CONFIG="$XDG_CONFIG_HOME"/notmuch/notmuchrc

$ export NMBGIT="$XDG_DATA_HOME"/notmuch/nmbug

npm ~/.npm




nvidia-settings ~/.nvidia-settings-rc $ nvidia-settings --config="$XDG_CONFIG_HOME"/nvidia/settings
openscad ~/.OpenSCAD [128] [129] Does not fully honour XDG Base Directory Specification, see [130]

Currently it hard-codes ~/.local/share.

OpenSSL ~/.rnd Seeding file .rnd's location can be set with RANDFILE environment variable per FAQ.
pass ~/.password-store $ export PASSWORD_STORE_DIR="$XDG_DATA_HOME"/pass
pidgin ~/.purple $ pidgin --config="$XDG_DATA_HOME"/purple
PulseAudio ~/.esd_auth Very likely generated by the module-esound-protocol-unix.so module. It can be configured to use a different location but it makes much more sense to just comment out this module in /etc/pulse/default.pa or "$XDG_CONFIG_HOME"/pulse/default.pa.
python-setuptools ~/.python-eggs $ export PYTHON_EGG_CACHE="$XDG_CACHE_HOME"/python-eggs
rclone ~/.rclone.conf $ rclone --config="$XDG_CONFIG_HOME"/rclone/rclone.conf
readline ~/.inputrc $ export INPUTRC="$XDG_CONFIG_HOME"/readline/inputrc
rlwrap ~/.*_history [131] $ export RLWRAP_HOME="$XDG_DATA_HOME"/rlwrap
screen ~/.screenrc $ export SCREENRC="$XDG_CONFIG_HOME"/screen/screenrc
stack ~/.stack [132] $ export STACK_ROOT="$XDG_DATA_HOME"/stack
subversion ~/.subversion [133] [134][135] $ svn --config-dir "$XDG_CONFIG_HOME"/subversion
task ~/.task


$ export TASKDATA="$XDG_DATA_HOME"/task

$ export TASKRC="$XDG_CONFIG_HOME"/task/taskrc

tig ~/.tigrc $ export TIGRC_USER="$XDG_CONFIG_HOME"/tig/tigrc
tmux ~/.tmux.conf [136] [137] $ tmux -f "$XDG_CONFIG_HOME"/tmux/tmux.conf


uncrustify ~/.uncrustify.cfg $ export UNCRUSTIFY_CONFIG="$XDG_CONFIG_HOME"/uncrustify/uncrustify.cfg
Unison ~/.unison $ export UNISON="$XDG_DATA_HOME"/unison
urxvtd ~/.urxvt/urxvtd-hostname $ export RXVT_SOCKET="$XDG_RUNTIME_DIR"/urxvtd
WeeChat ~/.weechat [138] $ export WEECHAT_HOME="$XDG_CONFIG_HOME"/weechat

$ weechat -d "$XDG_CONFIG_HOME"/weechat

wget ~/.wgetrc $ export WGETRC="$XDG_CONFIG_HOME/wgetrc"
wine ~/.wine [139] Winetricks uses XDG-alike location below for WINEPREFIX management:

$ mkdir -p "$XDG_DATA_HOME"/wineprefixes

$ export WINEPREFIX="$XDG_DATA_HOME"/wineprefixes/default

xorg-xauth ~/.Xauthority $ export XAUTHORITY="$XDG_RUNTIME_DIR"/Xauthority
xorg-xinit ~/.xinitrc $ export XINITRC="$XDG_CONFIG_HOME"/X11/xinitrc
xorg-xrdb ~/.Xresources


Ultimately you should be using Xresources and since these resources are loaded via xrdb you can specify a path such as $ xrdb -load ~/.config/X11/xresources.
xsel ~/.xsel.log [140] $ xsel --logfile "$XDG_CACHE_HOME"/xsel/xsel.log


Application Legacy Path Discussion Notes
AMule ~/.aMule
Apache Directory Studio ~/.ApacheDirectoryStudio
bash ~/.bashrc





[141] A specified bashrc can be sourced from /etc/bashrc

$ export HISTFILE="$XDG_DATA_HOME"/bash/history

cabal ~/.cabal [142] See discussion for potential workarounds. It is not very easy or straightforward but may be possible to emulate Base Directory compliance.
CUPS ~/.cups [143]
dbus ~/.dbus [144] This should be avoidable with kdbus [citation needed].
eclipse ~/.eclipse [145] Option -Dosgi.configuration.area=@user.home/.config/.. overrides but must be added to "$ECLIPSE_HOME"/eclipse.ini" rather than command line which means you must have write access to $ECLIPSE_HOME. (Arch Linux hard-codes $ECLIPSE_HOME in /usr/bin/eclipse)
emacs ~/.emacs


[146] It's possible to set HOME, but it has unexpected side effects. So far the most promising approach is modifying another Emacs environment variable to alter the load path and author your own site file which can manually load up your init file, but it changes the load process significantly.
Fetchmail ~/.fetchmailrc
Firefox ~/.mozilla [147]
GNU parallel ~/.parallel
idris ~/.idris [148]
julia ~/.juliarc.jl


[149] [150]
lldb ~/.lldb


mathomatic ~/.mathomaticrc


History can be moved by using rlwrap mathomatic -r with the RLWRAP_HOME environment set appropriately.
Mercurial ~/.hgrc You cannot append to the configuration search paths, just overwrite them completely. That means you need to be careful to add all default folders:

$ export HGRCPATH=/usr/lib/python2.7/site-packages/mercurial/default.d/:\ /etc/mercurial/hgrc:"${XDG_CONFIG_HOME}"/mercurial/hgrc

To find the default configuration paths:

$ env -u HGRCPATH hg debugconfig --debug | grep "read config"

milkytracker ~/.milkytracker_config [151]
mongodb ~/.mongorc.js


[152] This Stack Overflow thread suggests a partial workaround using command-line switch --norc.
ncmpc ~/.ncmpc
~/.netrc Like ~/.ssh, many programs expect this file to be here. These include projects like curl (CURLOPT_NETRC_FILE), ftp (NETRC), s-nail (NETRC), etc. While some of them offer alternative configurable locations, many do not such as w3m, wget and lftp.
NSS ~/.pki [153]
OpenSSH ~/.ssh [154] Assumed to be present by many ssh daemons and clients such as DropBear and OpenSSH.
palemoon ~/.moonchild productions [155]
perf ~/.debug Hardcoded in tools/perf/util/config.c:18.
~/.profile Used by the various shells and display managers.
python ~/.python_history All history from interactive sessions is saved to ~/.python_history by default since version 3.4, custom path can still be set the same way as in older versions (see this example).
racket ~/.racketrc
SeaMonkey ~/.mozilla [156]
Skype ~/.Skype [157]
SpamAssassin ~/.spamassassin
spectrwm ~/.spectrwm
SQLite ~/.sqlite_history [158][159]
Thunderbird ~/.thunderbird [160]
vim ~/.vim



Since 7.3.1178 vim will search for ~/.vim/vimrc if ~/.vimrc is not found.

$ mkdir -p "$XDG_CACHE_HOME"/vim/{undo,swap,backup}

set undodir=~/.cache/vim/undo
set directory=~/.cache/vim/swap
set backupdir=~/.cache/vim/backup
set viminfo+=n~/.cache/vim/viminfo
vimperator ~/.vimperatorrc [161] $ export VIMPERATOR_INIT=":source $XDG_CONFIG_HOME/vimperator/vimperatorrc"


wpa_cli ~/.wpa_cli_history
xdg-utils ~/.gnome For some reason the script xdg-desktop-menu hard-codes gnome_user_dir="$HOME/.gnome/apps". This is used by chromium amoung others.
xmonad ~/.xmonad [162]
xombrero ~/.xombrero [163]
zsh ~/.zshrc

~/.zprofile ~/.zshenv

~/.zlogin ~/.zlogout


[164] Consider exporting ZDOTDIR=$HOME/.config/zsh in ~/.zshenv (this is hardcoded due to the bootstrap problem). You could also add this to /etc/zsh/zshenv and avoid the need for any dotfiles in your HOME. Doing this however requires root privilege which may not be viable and is system-wide.

$ export HISTFILE="$XDG_DATA_HOME"/zsh/history

Library and language support

C99: Cloudef's simple implementation.
Officially in directory since [165].
Builtin support via GLib.Environment.
See get_user_cache_dir, get_user_data_dir, get_user_config_dir, etc.

See also