A Python package for determining platform-specific directories (e.g. user data, config, cache, logs). Handles the differences between macOS, Windows, Linux/Unix, Android, and iOS so you don't have to.
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.PathApplication 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)
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.
