platformdirs

4.9.4 verified Tue May 12 auth: no python install: verified quickstart: verified

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.

pip install platformdirs

Common errors

error ModuleNotFoundError: No module named 'platformdirs' ↓

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

fix

pip install platformdirs

error ImportError: The 'platformdirs' package is required ↓

cause 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

error ModuleNotFoundError: No module named 'platformdirs.macos' ↓

cause 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).

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

cause 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

Warnings

breaking macOS 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.

breaking Linux 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.

breaking Platform 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).

breaking Requires 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.

gotcha Directories 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.

gotcha site_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.

gotcha On 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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.04s 18.0M

3.10 slim (glibc) - - 0.02s 19M

3.11 alpine (musl) - - 0.07s 19.9M

3.11 slim (glibc) - - 0.05s 20M

3.12 alpine (musl) - - 0.05s 11.7M

3.12 slim (glibc) - - 0.05s 12M

3.13 alpine (musl) - - 0.04s 11.4M

3.13 slim (glibc) - - 0.04s 12M

3.9 alpine (musl) - - 0.03s 17.5M

3.9 slim (glibc) - - 0.02s 18M

Imports

PlatformDirs
wrong
```
from appdirs import AppDirs
```
correct
```
from platformdirs import PlatformDirs
```
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.

Quickstart verified last tested: 2026-04-23

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