platformdirs

A Python package for determining platform-specific directories (e.g. user data, config, cache, logs). Handles the differences between macOS, Windows, Linux/Unix, and Android so you don’t have to.

Quick start

from platformdirs import PlatformDirs

dirs = PlatformDirs("MyApp", "MyCompany")
dirs.user_data_dir  # ~/.local/share/MyApp (Linux)
dirs.user_config_dir  # ~/.config/MyApp (Linux)
dirs.user_cache_dir  # ~/.cache/MyApp (Linux)
dirs.user_state_dir  # ~/.local/state/MyApp (Linux)
dirs.user_log_dir  # ~/.local/state/MyApp/log (Linux)
dirs.user_documents_dir  # ~/Documents
dirs.user_downloads_dir  # ~/Downloads
dirs.user_runtime_dir  # /run/user/<uid>/MyApp (Linux)

For Path objects instead of strings:

from platformdirs import PlatformDirs

dirs = PlatformDirs("MyApp", "MyCompany")
dirs.user_data_path  # pathlib.Path('~/.local/share/MyApp')
dirs.user_config_path  # pathlib.Path('~/.config/MyApp')

Convenience functions for quick access:

from platformdirs import user_data_dir, user_config_path

user_data_dir("MyApp", "MyCompany")  # returns str
user_config_path("MyApp", "MyCompany")  # returns pathlib.Path

Directory types

• Data: Persistent application data (user_data_dir, site_data_dir)
• Config: Configuration files and settings (user_config_dir, site_config_dir)
• Cache: Cached data that can be regenerated (user_cache_dir, site_cache_dir)
• State: Non-essential runtime state like window positions (user_state_dir, site_state_dir)
• Logs: Log files (user_log_dir, site_log_dir)
• Runtime: Runtime files like sockets and PIDs (user_runtime_dir, site_runtime_dir)

Each type has both user_* (per-user, writable) and site_* (system-wide, read-only for users) variants.

Documentation

Full documentation is available at platformdirs.readthedocs.io:

• Getting started tutorial – learn core concepts through real-world examples
• How-to guides – recipes for common tasks and platform-specific tips
• API reference – complete list of functions and classes
• Platform details – default paths for each operating system

Contributions are welcome! See CONTRIBUTING.md for details.