appdirs

appdirs is a small, dependency-free Python module that answers a deceptively fiddly question: where should an application store its data, config, cache, and log files on the current operating system? It implements the platform-specific conventions for macOS, Windows (including roaming profiles), and Unix systems following the XDG Base Directory spec, exposing them as a handful of functions (user_data_dir, user_config_dir, user_cache_dir, user_log_dir, site_data_dir, site_config_dir) plus a convenience AppDirs class that bundles them together for one app name and author.

Because it ships as a single importable module with zero dependencies, many other Python packages have historically vendored a private copy of appdirs rather than adding it as an external dependency. The project has been officially deprecated by its maintainers in favor of platformdirs, a more actively maintained fork with broader platform support, but appdirs remains widely installed as a transitive dependency across the Python ecosystem, and its stable 1.4.4 API is still directly usable for straightforward, single-app use.

What You Get

• Six directory-resolution functions covering user and site data, config, cache, and log paths across macOS, Windows, and Unix
• An AppDirs convenience class that bundles all directory properties for a given app name, author, and version in one object
• XDG Base Directory spec compliance on Unix, including support for XDG_DATA_HOME, XDG_CONFIG_HOME, XDG_CACHE_HOME, and their _DIRS variants
• Windows roaming-profile awareness via a roaming flag that switches between CSIDL_APPDATA and CSIDL_LOCAL_APPDATA
• Optional per-version path isolation so multiple versions of the same app can keep separate data, cache, and log directories
• A single dependency-free module that’s easy to vendor directly or install standalone

Common Use Cases

• CLI tools storing user preferences in a config file without hardcoding a Unix-only or Windows-only path
• Desktop and command-line apps caching downloaded assets or build artifacts in the OS-correct cache directory
• Libraries that need a safe, writable location for logs without dictating a rigid directory structure to the calling application
• Packaging and installer tooling vendoring a private copy of appdirs to avoid taking on an external dependency

Under The Hood

Architecture appdirs.py is a single flat module with no internal package structure — the entire surface is roughly ten free functions (user_data_dir, site_data_dir, user_config_dir, site_config_dir, user_cache_dir, user_state_dir, user_log_dir) that each independently branch on a module-level system string (win32, darwin, or other) computed once at import time, plus a handful of private _get_win_folder_* fallback functions selected at import time based on which Windows API is importable (ctypes, JNA, winreg, or environment variables). The AppDirs class is a stateless facade that forwards constructor arguments to the module-level functions via properties. There is no dependency injection, no layering, and no real data flow beyond string path construction — it’s a flat set of utility functions with a consistent per-platform branching pattern repeated in each one, appropriate for its narrow scope but with clear duplication across functions.

Tech Stack The module has zero runtime dependencies outside the standard library (os, sys, and conditionally ctypes/winreg/jna on Windows). It’s distributed the classic setuptools/distutils way with py_modules=["appdirs"] for single-file distribution rather than a package directory, has no pyproject.toml or modern PEP 517 build backend, and targets a broad but dated compatibility matrix (Python 2.7 and 3.5–3.9 per its setup.py classifiers). CI runs on Travis per .travis.yml, with tox.ini driving the multi-version test matrix and a Dockerfile present for test environments.

Code Quality The test suite is a single file (test/test_api.py) with three unittest methods that mostly assert the return values are strings, without asserting actual per-platform path correctness or mocking the different system branches. There’s no linter or formatter configuration in the repo, and no type hints anywhere (Python 2.7 compatibility rules them out). The strongest quality signal is thorough docstrings on every public function, documenting typical directory values per platform and each parameter’s behavior in detail.

What Makes It Unique appdirs isn’t technically novel — it implements well-documented OS conventions (the XDG Base Directory spec, Windows CSIDL constants, macOS Library conventions) rather than inventing a new approach. Its historical significance was being an early, minimal, dependency-free reference implementation that other packages could vendor directly; that role has since been superseded by its own more actively maintained fork, platformdirs, which the project’s own README now points users toward.