platformdirs

library4.9.4pypypi✓ verified 52d ago

platformdirs is a Python library for determining platform-specific system directories — user data, config, cache, logs, runtime, and more. It is the actively maintained community fork of the now-deprecated appdirs package, implementing the XDG Base Directory Spec on Linux, ~/Library conventions on macOS, and AppData on Windows, with additional Android support. Current version is 4.9.4 (released 2026-03-05); the project releases frequently, with multiple minor/patch releases per month during active development periods.

devops

pip install platformdirs

github ↗package ↗docs ↗changelog ↗

Install & Compatibility

Where this runs

tested against v4.9.6 · 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

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.042s · 18MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 1.5s · import 0.036s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PlatformDirs

✓ from platformdirs import PlatformDirs

✗ from appdirs import AppDirs

appdirs is officially deprecated; PlatformDirs is the modern replacement. AppDirs is kept as an alias inside platformdirs for backward compatibility only.

AppDirs

✓ from platformdirs import AppDirs

AppDirs is a legacy alias for PlatformDirs; prefer PlatformDirs for new code.

user_data_dir

✓ from platformdirs import user_data_dir

Functional API — returns str. Use the _path suffix variant (e.g. user_data_path) to get a pathlib.Path instead.

user_data_path

✓ from platformdirs import user_data_path

Returns pathlib.Path. Every _dir function has a corresponding _path variant.

PlatformDirsABC

✓ from platformdirs import PlatformDirsABC

Abstract base class; import for type annotations or custom subclassing only.

OOP API with ensure_exists, plus functional API demonstrating both str and Path return types.

from platformdirs import PlatformDirs, user_data_dir, user_config_path # OOP API — preferred for repeated access to multiple dirs dirs = PlatformDirs(appname="MyApp", appauthor="MyCompany", version="1.0", ensure_exists=True) print(dirs.user_data_dir) # str: ~/.local/share/MyApp/1.0 (Linux) print(dirs.user_config_dir) # str: ~/.config/MyApp/1.0 (Linux) print(dirs.user_cache_dir) # str: ~/.cache/MyApp/1.0 (Linux) print(dirs.user_log_dir) # str: ~/.local/state/MyApp/1.0/log (Linux) print(dirs.user_state_dir) # str: ~/.local/state/MyApp/1.0 (Linux) print(dirs.user_runtime_dir) # str: /run/user/<uid>/MyApp/1.0 (Linux) # _path variants return pathlib.Path objects print(dirs.user_data_path) # pathlib.Path print(dirs.user_config_path) # pathlib.Path # Functional API — one-off lookups print(user_data_dir("MyApp", "MyCompany")) # str print(user_config_path("MyApp", "MyCompany")) # pathlib.Path

Debug

Known issues

breakingmacOS user_config_dir path has changed twice across major versions: 2.0.0 moved it to ~/Library/Preferences/<app>, then 3.0.0 moved it back to ~/Library/Application Support/<app>. Any stored config files at the old path will silently go unread after upgrading across these boundaries.

fix

After upgrading from <2.x or <3.x, migrate existing config files from the old path (~/Library/Preferences/<app>) to the new path (~/Library/Application Support/<app>) on first launch. Pin your platformdirs version in production if you cannot migrate users automatically.

affects: <3.0.0

breakingLinux user_log_dir was corrected in 2.6.0 from XDG_CACHE_HOME to XDG_STATE_HOME (i.e. ~/.cache/<app>/log → ~/.local/state/<app>/log). Existing log files at the old location are silently abandoned.

fix

If upgrading from <2.6.0, migrate or symlink ~/.cache/<app>/log to ~/.local/state/<app>/log, or pin to <2.6.0 until migration is complete.

affects: <2.6.0

breakingPlatform detection happens at import time, not at call time. Monkeypatching sys.platform after import has no effect on which platform class is used. This differs from the old appdirs behavior.

fix

To test platform-specific paths in tests, reload the platformdirs module after patching sys.platform, or use unittest.mock.patch combined with importlib.reload(platformdirs).

affects: >=2.0.0

breakingRequires Python >=3.10 as of the current release series. Older Python versions are not supported.

fix

Use platformdirs <4 for Python 3.8 or 3.9 support, or upgrade your Python runtime.

affects: >=4.x

gotchaDirectories are NOT created on disk by default. Accessing dirs.user_data_dir returns a string path but does not mkdir. Code that immediately opens a file in that path will raise FileNotFoundError.

fix

Pass ensure_exists=True to PlatformDirs() or the functional API call, or manually call Path(dirs.user_data_dir).mkdir(parents=True, exist_ok=True) before writing.

affects: all

gotchasite_data_dir and site_config_dir with multipath=True return a colon-separated string on Unix (os.pathsep-joined), not a list. Iterating the string character-by-character is a common mistake.

fix

Split with dirs.site_data_dir.split(os.pathsep) or use the iter_data_dirs() / iter_config_dirs() iterator methods on the PlatformDirs instance to get individual Path objects.

affects: all

gotchaOn Unix, running as root (uid 0) does NOT redirect user_*_dir to site_*_dir by default for backward compatibility. Root's XDG dirs point to /root/.local/share etc., not /usr/local/share.

fix

Pass use_site_for_root=True to PlatformDirs() when you want system-wide paths when running as root on Unix.

affects: >=4.8.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'platformdirs'

The 'platformdirs' package is not installed in the Python environment being used, or the environment is not correctly activated.

fix

pip install platformdirs

ImportError: The 'platformdirs' package is required

This error often occurs when bundling an application with PyInstaller; a dependency (like pkg_resources) requires 'platformdirs', but PyInstaller fails to detect and include it automatically.

fix

Add 'platformdirs' as a hidden import to your PyInstaller command or .spec file: `pyinstaller --hidden-import platformdirs your_script.py`

ModuleNotFoundError: No module named 'platformdirs.macos'

When using PyInstaller, platform-specific submodules like 'platformdirs.macos' are dynamically imported, which PyInstaller may fail to detect and include, leading to this error on the respective OS.

fix

Explicitly include the platform-specific submodule as a hidden import in your PyInstaller command or .spec file: `pyinstaller --hidden-import platformdirs.macos your_script.py` (adjust 'macos' for other platforms like 'windows' or 'unix' if applicable).

AttributeError: module 'platformdirs' has no attribute 'site_cache_dir'

A dependent library is attempting to access an attribute or function (e.g., 'site_cache_dir') that exists in a newer version of 'platformdirs' but is missing from the currently installed older version.

fix

Upgrade the 'platformdirs' package to the latest version or a version compatible with your dependent library: `pip install --upgrade platformdirs`

Upgrade

Version history

4.10.0latest on PyPI

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

seranking-bot

ahrefsbot

Amazon

Resources

githubhttps://github.com/tox-dev/platformdirs ↗

packagehttps://pypi.org/project/platformdirs/ ↗

docshttps://platformdirs.readthedocs.io ↗

changeloghttps://platformdirs.readthedocs.io/en/latest/changelog.html ↗