XDG Base Directories

6.0.2 · active · verified Sun Apr 12

The `xdg-base-dirs` library provides Python functions to retrieve paths adhering to the XDG Base Directory Specification, which defines standard locations for user-specific data, configuration, and cache files. As of version 6.0.2, it is actively maintained with frequent minor updates and fixes, and a major release approximately once a year.

Warnings

breaking The library was renamed from `xdg` to `xdg-base-dirs` in v6.0.0 due to an import collision with another package. This change requires updating both your dependency name (e.g., in `requirements.txt`) and your import statements.
Fix: Change `pip install xdg` to `pip install xdg-base-dirs` and `import xdg` to `from xdg_base_dirs import ...`.
breaking Python 3.10 or later is now required for `xdg-base-dirs`.
Fix: Ensure your project is running on Python 3.10 or newer.
breaking The API refactored in v5.0.0 to provide functions rather than module-level variables. While the old variable-based API is maintained for backward compatibility, it is no longer documented and may be removed in future major versions. Functions ensure that environment variable changes made after import are respected.
Fix: Replace `xdg.XDG_CONFIG_HOME` with `xdg_config_home()` and similar for other paths.
breaking As of v4.0.0, paths are returned as `pathlib.Path` objects instead of strings. This is generally preferred but requires conversion if your code expects string paths.
Fix: If string paths are required, wrap the `pathlib.Path` object in `os.fspath()`. Example: `import os; config_path_str = os.fspath(xdg_config_home())`.
gotcha Relative paths defined in XDG environment variables (e.g., `XDG_CONFIG_HOME`) are considered invalid by the specification and are ignored by the library. Only absolute paths are accepted.
Fix: Ensure that any custom XDG environment variables are set to absolute paths.

Install

pip install xdg-base-dirs Install latest version

Imports

xdg_config_home
```
from xdg_base_dirs import xdg_config_home
```
The library was renamed from `xdg` to `xdg-base-dirs` in v6.0.0 due to an import collision with PyXDG. The import path changed from `xdg` to `xdg_base_dirs`. Additionally, the recommended API shifted from module-level variables (e.g., `xdg.XDG_CONFIG_HOME`) to functions (e.g., `xdg_config_home()`) in v5.0.0.

Quickstart

This quickstart demonstrates how to import and use the XDG functions to retrieve standard directory paths. The functions return `pathlib.Path` objects, which are the recommended way to handle file system paths in modern Python.

from xdg_base_dirs import xdg_config_home, xdg_data_home, xdg_cache_home, xdg_runtime_dir

# Get the path to the user's XDG config directory
config_dir = xdg_config_home()
print(f"XDG Config Home: {config_dir}")

# Get the path to the user's XDG data directory
data_dir = xdg_data_home()
print(f"XDG Data Home: {data_dir}")

# Paths are returned as pathlib.Path objects
assert isinstance(config_dir, type(xdg_config_home()))

view raw JSON →