platformdirs

Common errors

• 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

• 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`

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

• 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

• pip install platformdirs pip

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

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