A small Python package for determining appropriate platform-specific dirs, e.g. a `user data dir`.
Project Links
Meta
Maintainer: Bernát Gábor, Julian Berman, Ofek Lev, Ronny Pfannschmidt
Requires Python: >=3.11
Classifiers
Development Status
- 5 - Production/Stable
Intended Audience
- Developers
Operating System
- OS Independent
Programming Language
- Python
- Python :: 3 :: Only
- Python :: 3.11
- Python :: 3.12
- Python :: 3.13
- Python :: 3.14
- Python :: 3.15
- Python :: Implementation :: CPython
- Python :: Implementation :: PyPy
Topic
- Software Development :: Libraries :: Python Modules
platformdirs
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.
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.
4.14.0
Oct 28, 2026
4.13.7
Oct 28, 2026
4.13.6
Oct 27, 2026
4.13.5
Oct 19, 2026
4.13.4
Oct 17, 2026
4.13.3
Oct 16, 2026
4.13.2
Oct 16, 2026
4.13.1
Oct 15, 2026
4.13.0
Oct 11, 2026
4.12.4
Oct 07, 2026
4.12.3
Oct 03, 2026
4.12.2
Sep 29, 2026
4.12.1
Sep 28, 2026
4.12.0
Sep 26, 2026
4.11.15
Sep 26, 2026
4.11.14
Sep 25, 2026
4.11.13
Sep 25, 2026
4.11.12
Sep 22, 2026
4.11.11
Sep 19, 2026
4.11.10
Sep 18, 2026
4.11.9
Sep 16, 2026
4.11.8
Sep 08, 2026
4.11.7
Sep 01, 2026
4.11.6
Sep 01, 2026
4.11.5
Aug 27, 2026
4.11.4
Aug 24, 2026
4.11.3
Aug 13, 2026
4.11.2
Aug 10, 2026
4.11.1
Aug 07, 2026
4.11.0
Jul 21, 2026
4.10.1
Jul 18, 2026
4.10.0
May 28, 2026
4.9.6
Apr 09, 2026
4.9.4
Mar 05, 2026
4.9.2
Feb 16, 2026
4.9.1
Feb 14, 2026
4.9.0
Feb 14, 2026
4.8.0
Feb 14, 2026
4.7.1
Feb 13, 2026
4.7.0
Feb 12, 2026
4.6.0
Feb 12, 2026
4.5.1
Dec 05, 2025
4.5.0
Oct 08, 2025
4.4.0
Aug 26, 2025
4.3.8
May 07, 2025
4.3.7
Mar 19, 2025
4.3.6
Sep 17, 2024
4.3.5
Sep 17, 2024
4.3.4
Sep 17, 2024
4.3.3
Sep 13, 2024
4.3.2
Sep 08, 2024
4.3.1
Sep 07, 2024
4.3.0
Sep 07, 2024
4.2.2
May 15, 2024
4.2.1
Apr 23, 2024
4.2.0
Jan 31, 2024
4.1.0
Dec 04, 2023
4.0.0
Nov 10, 2023
3.11.0
Oct 02, 2023
3.10.0
Jul 29, 2023
3.9.1
Jul 15, 2023
3.9.0
Jul 15, 2023
3.8.1
Jul 06, 2023
3.8.0
Jun 23, 2023
3.7.0
Jun 21, 2023
3.6.0
Jun 18, 2023
3.5.3
Jun 10, 2023
3.5.2
Jun 10, 2023
3.5.1
May 11, 2023
3.5.0
Apr 27, 2023
3.4.0
Apr 26, 2023
3.3.0
Apr 25, 2023
3.2.0
Mar 25, 2023
3.1.1
Mar 10, 2023
3.1.0
Mar 03, 2023
3.0.0
Feb 06, 2023
2.6.2
Dec 28, 2022
2.6.1
Dec 28, 2022
2.6.0
Dec 07, 2022
2.5.4
Nov 13, 2022
2.5.3
Nov 06, 2022
2.5.2
Apr 18, 2022
2.5.1
Feb 19, 2022
2.5.0
Feb 09, 2022
2.4.1
Dec 26, 2021
2.4.0
Sep 25, 2021
2.3.0
Aug 30, 2021
2.2.0
Jul 29, 2021
2.1.0
Jul 25, 2021
2.0.2
Jul 13, 2021
2.0.0
Jul 12, 2021
2.0.0a3
May 14, 2021
2.0.0a2
May 13, 2021
2.0.0a1
May 13, 2021
Wheel compatibility matrix
Files in release
No dependencies