xdg-base-dirs

What it is and what it does

xdg-base-dirs is a lightweight utility that implements the XDG Base Directory Specification, a freedesktop.org standard that defines where Unix/Linux applications should store user-specific files like configuration, cache, and data. It returns pathlib.Path objects for each directory type, reading from the corresponding XDG environment variables (XDG_CONFIG_HOME, XDG_CACHE_HOME, etc.) and falling back to specification-defined defaults when those variables are unset, empty, or contain relative paths.

The package eliminates the need to duplicate XDG path logic across multiple utilities. It has zero runtime dependencies and is small enough to copy directly into a project if preferred. It supports Python 3.10 through 3.13 and is actively maintained.

Use it for:

• Store application configuration files in the user's XDG config directory instead of hardcoding ~/.config paths.
• Manage application cache files in XDG cache directories that respect user environment variable overrides.
• Build command-line tools that follow the XDG specification for multiplatform Unix/Linux compatibility.
• Retrieve runtime directories for temporary sockets or IPC files via xdg_runtime_dir().
• Access XDG data and state directories as lists to search multiple locations for application files.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides functions to retrieve XDG Base Directory Specification paths for cache, config, data, runtime, and state directories, returning pathlib.Path objects with sensible defaults when environment variables are unset.

Yes. This is a stable, dependency-free utility that solves a real problem for any Python tool dealing with user files on Unix/Linux systems. Low install friction, permissive license, active maintenance, and no known vulnerabilities make it a straightforward addition to projects that need XDG compliance.

Install

xdg-base-dirs on PyPI

pip install xdg-base-dirs

uv add xdg-base-dirs

poetry add xdg-base-dirs

Installing xdg-base-dirs

Before you install

Low friction: pure Python, no runtime dependencies, single-file distribution. Active maintenance with recent commits and stable release history since 2023.

License in practice

ISC license is permissive, allowing commercial and private use with minimal restrictions—suitable for most projects.

Quickstart

from xdg_base_dirs import xdg_config_home, xdg_cache_home

config_dir = xdg_config_home()
cache_dir = xdg_cache_home()

Requires Python 3.10 or later.

Verify before relying

• Whether the package handles Windows XDG paths correctly given the OS classifier includes Windows but XDG is primarily a Unix/Linux standard.

Package facts

Evidence: xdg_base_dirs-6.0.2-py3-none-any.whl

Keywords: xdg, base, directory, specification

Tags

More Utilities packages