Dotfiles matter!

Please stop dumping files in users’ $HOME directories.

We 💙 dotfiles!

Dotfiles are important. We use them every day for storing configuration for all kinds of applications, knowingly or otherwise. You know the ones, hidden in your $HOME directory, ~/.ssh/ for your ssh keys, or ~/.Xauthority (whatever the heck that does). Something you may not know is these are legacy locations for configuration. Please do not copy their behaviour. Your application’s configuration may be the most important thing on a user’s machine. There are now standardised locations on major platforms for applications to store user-specific configuration.

Your application should not be dumping random files into an unconfigurable location in the user’s home directory.

Configuration is important and so is its location.

Your application’s configuration is important. A user may want to back it up as an important part of their system, control its permissions, handle it with a script on their system or just inspect it. They may not want their configuration stored in $HOME, for example:

  • they’re on a machine that isn’t under their physical control and ~/.config is mounted over the network from their personal machine;
  • an automated script they run backs up their ~/permanent/configuration directory every night as their OS is stored on a RAMdisk every boot;
  • they prefer to version control their configuration files using git, with a configuration directory managed over different branches;
  • the user simply wants to have a clean and consistent $HOME directory and filesystem.

When you hardcode your application’s configuration and data directory as ~/.my_application, you are contributing to a trend that leaves people’s machines less secure, less consistent, and ultimately less productive.

TL;DR: Where should you store application data?


As of 2023, most major Linux distributions and desktop environments adhere to the XDG Base Directory Specification, which defines standard locations for different types of files: cache, configuration data, and state (… more data). The specification defines environment variables which if defined provide an absolute path for that kind of data. Following are the expected locations for application files in order of importance (each path begins from $HOME):

Cache $XDG_CACHE_HOME $HOME/.cache Non-essential non-persistent data files, logs, thumbnails etc.
Configuration $XDG_CONFIG_HOME $HOME/.config Persistent configuration data files
Application Data $XDG_DATA_HOME $HOME/.local/share Data files like history, databases, logs, “stuff”
Executable Files n/a (sigh) $HOME/.local/bin User-facing executable files (i.e. the output of `cc -o <file>`)
Runtime Data $XDG_RUNTIME_DIR Should be provided by your system This is for runtime data (sockets, pipes, whatever.)

There are more directories, but don’t overcomplicate things. Even just using $XDG_CACHE_HOME and $XDG_CONFIG_HOME is a lifesaver.


Apple provides the File System Programming Guide, which defines expected storage locations, again for: cache, configuration and state (data). Following are the expected locations for application files (where ~ is $HOME, the current user’s home directory):

Cache ~/Library/Caches Non-essential, non-persistent application data
Application Data, Configuration ~/Library/Application Support Persistent configuration data files and “private” application data
Applications ~/Applications Applications

When writing a cross-platform application, some developers like to enable XDG support on Darwin, too (see Linux/Unix section).

Please share the word.

Users matter. Please help the movement to clean up users’ $HOME directories and standardise configuration by spreading the word, opening issues (preferably with PRs, not to annoy maintainers!), and contributing to a world where application data can roam freely in the nature preserve of specification.


If you have opinions or corrections please share them with me at offsetcyan <at> Thanks!

Author: anonymous

Created: 2023-09-30 Sat 18:32