XDG Base Directories Cheat Sheet

Date Created: 2026-06-09
Last Updated: 2026-07-17

1. Introduction

The XDG Base Directory Specification defines conventional locations for user-specific configuration, cache, and application data on Linux and other Unix-like systems.

Understanding these directories helps keep the home directory tidy, simplifies backups, and improves portability between systems. Modern command-line tools and desktop applications increasingly follow these conventions.

For developers working across Linux, macOS, Docker containers, and remote servers, adopting XDG-style paths can reduce platform-specific complexity.

---

2. Data Schema

A. Column Definitions

• Directory: Standard XDG directory.
• Default Location: Path used when the corresponding environment variable is unset.
• Purpose: Intended usage of the directory.

---

B. Design Policy

• User Scope: XDG directories are user-specific and reside under the user’s home directory.
• Portable Configuration: Applications should respect XDG environment variables when present.
• Separation of Concerns: Configuration, cache, and application data should be stored separately.

---

3. XDG Base Directory Reference

Directory	Default Location	Purpose
XDG_CONFIG_HOME	~/.config	User configuration files
XDG_CACHE_HOME	~/.cache	Non-essential cached data
XDG_DATA_HOME	~/.local/share	User application data
XDG_STATE_HOME	~/.local/state	Persistent state data (logs, history, etc.)
HOME	~	User home directory

Typical Examples

Configuration

~/.config/git/
~/.config/pip/
~/.config/nvim/
~/.config/gh/
~/.config/whisper-smith/

Cache

~/.cache/pip/
~/.cache/uv/
~/.cache/pytest/
~/.cache/matplotlib/

Cache files should be considered disposable and may be safely deleted when troubleshooting or reclaiming disk space.

Application Data

~/.local/share/applications/
~/.local/share/fonts/
~/.local/share/whisper-smith/

This directory is intended for user data that should survive cache cleanup.

State Data

~/.local/state/

Examples:

~/.local/state/app.log
~/.local/state/history

State data is neither configuration nor cache.

---

4. Shell Setup

Add these exports to a shell configuration file such as ~/.zshrc, ~/.bashrc, or ~/.profile to make the standard XDG paths explicit for interactive shells and CLI tools.

export XDG_CONFIG_HOME="$HOME/.config"
export XDG_DATA_HOME="$HOME/.local/share"
export XDG_STATE_HOME="$HOME/.local/state"
export XDG_CACHE_HOME="$HOME/.cache"

Create the directories once so tools can write to them immediately:

mkdir -p "$XDG_CONFIG_HOME" "$XDG_DATA_HOME" "$XDG_STATE_HOME" "$XDG_CACHE_HOME"

---

5. Linux vs macOS Notes

Although macOS traditionally uses:

~/Library/Application Support/

many modern cross-platform CLI tools use:

~/.config/

on macOS as well.

For developer-oriented Python projects, the following convention works well:

Environment	Recommended Location
macOS Development	~/.config//
Linux Development	~/.config//
Linux Production Server	/etc//

Example:

macOS:
~/.config/whisper-smith/secrets.env

Ubuntu Server:
/etc/whisper-smith/secrets.env

---

6. Secret Management Example

Recommended permissions:

directory : 700
file      : 600

Example:

mkdir -p ~/.config/whisper-smith
chmod 700 ~/.config/whisper-smith
chmod 600 ~/.config/whisper-smith/secrets.env

Result:

drwx------ ~/.config/whisper-smith
-rw------- ~/.config/whisper-smith/secrets.env

---

7. References

• XDG Base Directory Specification

---

8. Maintenance Notes

• Extensibility: Additional XDG directories can be added as standards evolve.
• Generation: This page is maintained manually as a developer cheat sheet.
• Interpretation: The defaults shown assume the corresponding XDG environment variables are not explicitly set.