Install & Compatibility
Where this runs
tested against v0.28 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BaseDirectory
✓ from xdg import BaseDirectory
PyXDG's modules are exposed under the 'xdg' top-level package.
DesktopEntry
✓ from xdg import DesktopEntry
PyXDG's modules are exposed under the 'xdg' top-level package.
Mime
✓ from xdg import Mime
PyXDG's modules are exposed under the 'xdg' top-level package.
Menu
✓ from xdg import Menu
PyXDG's modules are exposed under the 'xdg' top-level package.
IconTheme
✓ from xdg import IconTheme
PyXDG's modules are exposed under the 'xdg' top-level package.
This example demonstrates how to use `xdg.BaseDirectory` to get standard XDG paths and `xdg.Mime` to determine a file's MIME type.
import os
from xdg import BaseDirectory, Mime
# Get user's data home directory
data_home = BaseDirectory.xdg_data_home
print(f"XDG Data Home: {data_home}")
# Get preferred configuration directories
config_dirs = BaseDirectory.xdg_config_dirs
print(f"XDG Config Dirs: {config_dirs}")
# Find the MIME type of a file (example with a dummy file)
# Create a dummy file for demonstration
dummy_file_path = os.path.join(data_home, 'test.txt')
with open(dummy_file_path, 'w') as f:
f.write('Hello, PyXDG!')
mime_type = Mime.get_type(dummy_file_path)
print(f"MIME type of '{dummy_file_path}': {mime_type}")
# Clean up dummy file
os.remove(dummy_file_path)
Debug
Known issues
breakingPyXDG version 0.27 fixed compatibility issues with Python >= 3.8.4, specifically regarding menu processing. Older versions might encounter `AttributeError` or unexpected behavior.fixUpgrade to PyXDG 0.27 or newer.
affects: <0.27
deprecatedThe `Rule.compile()` method in `xdg.Menu` was removed in PyXDG 0.24. Code relying on this method will break.fixReview `xdg.Menu` documentation for alternative methods for processing filter rules. The XML parsing was also reworked in 0.26.
affects: <0.24
gotchaThere is a known namespace collision with another package named `xdg` (which was later renamed to `xdg-base-dirs`). Installing both `pyxdg` and `xdg` (or `xdg-base-dirs`) might lead to import errors or unexpected behavior due to both trying to provide the `xdg` top-level package.fixIf you explicitly need functionality from `xdg-base-dirs`, consider using virtual environments to isolate dependencies or ensure that only one of the packages providing the `xdg` namespace is installed in your environment. Prioritize `pyxdg` if you need the broader freedesktop.org standard implementations.
affects: All versions when `xdg` or `xdg-base-dirs` are also installed
gotchaThe `xdg.BaseDirectory.get_runtime_dir()` method, when called with `strict=True` (the default), will not create the runtime directory if it doesn't exist or if permissions are incorrect, returning `None`. This can be a silent failure if not handled.fixAlways check the return value of `get_runtime_dir()`. If a fallback or creation logic is desired, call it with `strict=False` (e.g., `BaseDirectory.get_runtime_dir(strict=False)`).
affects: All versions
gotchaWhen finding a file's MIME type, `xdg.Mime.get_type()` tries to use file contents and falls back to the name. If `name_pri` is set to 100 or higher, it prioritizes the filename. This can lead to incorrect MIME type detection if a file has a misleading extension and `name_pri` is not handled carefully.fixBe aware of the `name_pri` parameter in `xdg.Mime.get_type()`. If content-based detection is critical, ensure `name_pri` is set to a value less than 100 (its default behavior usually prioritizes content). For filename-only guessing, use `xdg.Mime.get_type_by_name()`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'xdg'
The 'pyxdg' package, which provides the 'xdg' module, is not installed in the current Python environment.
AttributeError: module 'pyxdg' has no attribute 'BaseDirectory'
The 'pyxdg' package exposes its modules (like BaseDirectory and Menu) under the 'xdg' namespace, not directly under 'pyxdg'.
fixInstead of `import pyxdg`, use `import xdg` or `from xdg import BaseDirectory` to access the modules directly.
AttributeError: type object 'BaseDirectory' has no attribute 'data_home'
You are attempting to access an XDG path attribute on `xdg.BaseDirectory` using an incorrect name; the correct attributes are prefixed with `xdg_` (e.g., `xdg_data_home`).
fixUse the correct attribute names, such as `xdg.BaseDirectory.xdg_data_home` or `xdg.BaseDirectory.xdg_config_dirs`.
Upgrade
Version history
0.28latest on PyPI · released Jun 5, 2022
Audit
Dependencies
No dependency data recorded yet.