platformdirs

platformdirs (the maintained fork of the original appdirs) gives Python applications a single API for finding the correct OS-conventional directory for application data, configuration, cache, logs, and runtime files. It abstracts away the differences between macOS, Windows, Linux/Unix (including XDG Base Directory spec compliance), and Android, so applications don’t hardcode ~/.config or %APPDATA% paths themselves.

Beyond application-scoped directories, it also exposes standard user media folders (Documents, Downloads, Pictures, Desktop, and more) that aren’t tied to a specific app name. Every directory is available as both a string path and a pathlib.Path, via either a PlatformDirs object or standalone convenience functions.

What You Get

• A PlatformDirs(appname, appauthor) class exposing user_data_dir, user_config_dir, user_cache_dir, user_state_dir, user_log_dir, and user_runtime_dir (plus site_* system-wide equivalents)
• Both string-path (user_config_dir) and pathlib.Path (user_config_path) accessors for every directory kind
• Standalone convenience functions (user_data_dir(), user_config_path(), etc.) for one-off lookups without instantiating a class
• User media directory accessors — Documents, Downloads, Pictures, Videos, Music, Desktop, Templates, Fonts, and more — not scoped to an app name
• Per-platform backends (unix.py, macos.py, windows.py, android.py) implementing XDG Base Directory spec on Linux, Apple conventions on macOS, and the Windows/Android equivalents

Common Use Cases

• Storing a CLI tool’s config file in the OS-correct location instead of hardcoding ~/.config/myapp
• Locating a safe, writable cache directory for downloaded assets or computed artifacts
• Finding the right log directory per platform for a desktop or CLI application
• Migrating from the unmaintained appdirs package to a drop-in, actively maintained replacement
• Locating standard user folders (Downloads, Documents) for file-picker defaults in a cross-platform app

Under The Hood

Architecture: The public API in src/platformdirs/api.py defines an abstract base with all directory properties; unix.py, macos.py, windows.py, and android.py each provide a platform-specific subclass implementing those properties according to that OS’s conventions (XDG spec on Linux via _xdg.py, ~/Library/... on macOS, %APPDATA%/%LOCALAPPDATA% on Windows). __init__.py picks the correct backend at import time based on sys.platform and re-exports both the class and convenience functions.

Tech Stack: Pure Python with zero required runtime dependencies, supporting Python 3.9+. Packaged with a standard pyproject.toml/hatchling build, ships py.typed for full type-checker support, and publishes wheels plus an sdist to PyPI on every tagged release.

Code Quality: Each platform backend has a dedicated test module (tests/test_unix.py, test_macos.py, test_windows.py, test_android.py), plus test_api.py for the shared interface and test_comp_with_appdirs.py explicitly testing parity/behavioral differences against the legacy appdirs package it forked from. CI runs across all four backends and multiple Python versions via GitHub Actions.

API Design: The dual surface — a PlatformDirs class for apps that need many directories at once, plus flat convenience functions (user_data_dir(appname)) for one-off lookups — lets callers pick the ergonomics that fit their use case with zero required configuration beyond an app name.