xdg-base-dirs
Variables defined by the XDG Base Directory Specification
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.10 or later.
- Low friction: pure Python, no runtime dependencies, single-file distribution.
- Active maintenance with recent commits and stable release history since 2023.
License · maintenance · safety
ISC (permissive) — ISC license is permissive, allowing commercial and private use with minimal restrictions—suitable for most projects.
last release 2024-10-19 (664 days) · last repo commit 2026-08-02 · 160 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 496,994 downloads/mo, #6,333 on PyPI
Alternatives
Verify before relying
from xdg_base_dirs import xdg_config_home, xdg_cache_home
config_dir = xdg_config_home()
cache_dir = xdg_cache_home()- Whether the package handles Windows XDG paths correctly given the OS classifier includes Windows but XDG is primarily a Unix/Linux standard.
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 on it.
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
Before you install
Low friction: pure Python, no runtime dependencies, single-file distribution. Active maintenance with recent commits and stable release history since 2023.
Requires Python 3.10 or later.
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()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 the current Python release <4.0,>=3.10 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | None |
| Maintenance | Actively maintained 664 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 496,994 / month, #6,333 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableIntended Audience :: DevelopersLicense :: OSI ApprovedNatural Language :: EnglishOperating System :: Microsoft :: WindowsOperating System :: UnixProgramming Language :: Python :: 3Programming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13 |
Evidence: xdg_base_dirs-6.0.2-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “xdg base directory paths”
- xdg-base-dirsProvides functions to retrieve XDG Base Directory Specification paths…
- xdgProvides functions to retrieve XDG Base Directory Specification paths…
- appdirsDetermines the correct platform-specific directory for storing…
Give your agent the search over MCP, or paste the wish link into any chat.
More Utilities packages
Converts domain names between Unicode and ASCII-compatible encoding (Punycode) according to IDNA 2008 and Unicode Technical Standard 46, with security validation and broader script coverage than the standard library.
Install it if you work with internationalized domain names, need to validate domains, or use HTTP clients that depend on it transitively.
Detects and normalizes text encoding from unknown or ambiguous sources, supporting all IANA character sets that Python's core library provides codecs for, with the ability to register custom codecs.
Setuptools is a Python build backend and package management tool that handles building, distributing, and installing Python packages, including support for C/C++ extension modules.
Pluggy provides a plugin system that lets you define hook specifications and register implementations to be called in sequence, enabling extensible Python applications without tight coupling.
Install it if you're building an extensible application or framework.
Pygments is a syntax highlighter that colorizes source code and text in over 500 languages and formats, outputting to HTML, LaTeX, RTF, SVG, images, or ANSI terminal sequences.
Install it if you need to display or transform source code.
Six provides utility functions to write Python code that runs on both Python 2.7 and Python 3.3+, smoothing over language differences between the two versions.
See also xdg · appdirs · platformdirs · pyprojroot · scantree · findlibs · pathlib-abc · pyrootutils · pystow · path.py