| single |
# platformdirs
[PyPI version]
[Python versions]
[CI]
[Downloads]
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
```python
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//MyApp (Linux)
```
For Path objects instead of strings:
```python
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:
```python
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.
|