Registry / serialization / xdg-base-dirs

xdg-base-dirs

library6.0.2pypypi✓ verified 23d ago

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.

serialization

pip install xdg-base-dirs

github ↗package ↗

INSTALL

IMPORT

SIG · XDG-BASE-DIRS

xdg-base-dirs

serializationpythonv6.0.2

Install

1.5s avg

Import

14ms

Disk

15MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v6.0.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 1.5s

py 3.11

✓ —

✓ 1.6s

py 3.12

✓ —

✓ 1.5s

py 3.13

✓ —

✓ 1.4s

py 3.9

✕ build_error

15MB installed

● package 15MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

xdg_config_home

✓ from xdg_base_dirs import xdg_config_home

✗ import xdg

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.

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()))

Debug

Known issues

breakingThe 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 ...`.

affects: >=6.0.0

breakingPython 3.10 or later is now required for `xdg-base-dirs`.

fix

Ensure your project is running on Python 3.10 or newer.

affects: >=6.0.0

breakingThe 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.

affects: >=5.0.0

breakingAs 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())`.

affects: >=4.0.0

gotchaRelative 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.

affects: >=5.0.2

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'xdg_base_dirs'

The `xdg-base-dirs` library has not been installed in your Python environment or the import statement uses an incorrect module name.

fix

pip install xdg-base-dirs

AttributeError: module 'xdg_base_dirs' has no attribute 'xdg_cache_path'

You are attempting to access a non-existent function or attribute named `xdg_cache_path`; the correct function name for the cache home directory is `xdg_cache_home()`.

fix

import xdg_base_dirs
path = xdg_base_dirs.xdg_cache_home()

ModuleNotFoundError: No module named 'xdg'

You are trying to import the library using the incorrect module name `xdg`; the correct module name for the `xdg-base-dirs` library is `xdg_base_dirs`.

fix

import xdg_base_dirs

Upgrade

Version history

6.0.2latest on PyPI · released Oct 19, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/srstevenson/xdg-base-dirs ↗

packagehttps://pypi.org/project/xdg-base-dirs/ ↗