{"id":4857,"library":"xdg-base-dirs","title":"XDG Base Directories","description":"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.","status":"active","version":"6.0.2","language":"en","source_language":"en","source_url":"https://github.com/srstevenson/xdg-base-dirs","tags":["XDG","filesystem","paths","configuration","cache","data"],"install":[{"cmd":"pip install xdg-base-dirs","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import xdg","symbol":"xdg_config_home","correct":"from xdg_base_dirs import xdg_config_home"}],"quickstart":{"code":"from xdg_base_dirs import xdg_config_home, xdg_data_home, xdg_cache_home, xdg_runtime_dir\n\n# Get the path to the user's XDG config directory\nconfig_dir = xdg_config_home()\nprint(f\"XDG Config Home: {config_dir}\")\n\n# Get the path to the user's XDG data directory\ndata_dir = xdg_data_home()\nprint(f\"XDG Data Home: {data_dir}\")\n\n# Paths are returned as pathlib.Path objects\nassert isinstance(config_dir, type(xdg_config_home()))\n","lang":"python","description":"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."},"warnings":[{"fix":"Change `pip install xdg` to `pip install xdg-base-dirs` and `import xdg` to `from xdg_base_dirs import ...`.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Ensure your project is running on Python 3.10 or newer.","message":"Python 3.10 or later is now required for `xdg-base-dirs`.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Replace `xdg.XDG_CONFIG_HOME` with `xdg_config_home()` and similar for other paths.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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())`.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure that any custom XDG environment variables are set to absolute paths.","message":"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.","severity":"gotcha","affected_versions":">=5.0.2"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}