---
id: xdg-base-dirs
version: "6.0.2"
license: ISC
license_treatment: permissive
maintenance: active
---

# xdg-base-dirs — Variables defined by the XDG Base Directory Specification

License: permissive · Maintenance: active · Downloads: 497.0K/mo

## 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 above — 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

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

- License: ISC (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 497.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

xdg base directory paths, xdg config home cache, freedesktop base directories, user config data directories, xdg runtime directory, xdg specification implementation, application config paths, xdg-specification, file-paths, unix-linux

[View on SkillFed](https://skillfed.io/packages/xdg-base-dirs) · [View on PyPI](https://pypi.org/project/xdg-base-dirs/)