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

Application directories — scoped to your app name and version:

• Data: Persistent application data (user_data_dir, site_data_dir)
• Config: Configuration files and settings (user_config_dir, site_config_dir)
• Preference: User preferences, distinct from config on macOS (user_preference_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)

App dirs have both user_* (per-user, writable) and site_* (system-wide, read-only) variants where applicable.

User media directories — standard user-facing folders, not scoped to app name:

• Documents (user_documents_dir), Downloads (user_downloads_dir)
• Pictures (user_pictures_dir), Videos (user_videos_dir), Music (user_music_dir)
• Desktop (user_desktop_dir), Projects (user_projects_dir)
• Public share (user_publicshare_dir), Templates (user_templates_dir)
• Fonts (user_fonts_dir) — user-writable font installation directory
• Executable (user_bin_dir, site_bin_dir), Applications (user_applications_dir, site_applications_dir)

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.