Changelog¶

4.10.0 (2026-05-28)¶

✨ feat: add user_publicshare_dir, user_templates_dir, user_fonts_dir, user_preference_dir PR #491
✨ feat: add user_projects_dir for $XDG_PROJECTS_DIR PR #490
chore: improve platformdirs maintenance path PR #488 - by @lphuc2250gma

4.9.6 (2026-04-09)¶

🐛 fix(release): use double quotes for tag variable expansion PR #477

4.9.5 (2026-04-06)¶

📝 docs(appauthor): clarify None vs False on Windows PR #476
Separates implementations of macOS dirs that share a default PR #473 - by @Goddesen
Remove persist-credentials: false from release job PR #472
fix: do not duplicate site dirs in Unix.iter_{config,site}_dirs() when use_site_for_root is active PR #469 - by @viccie30
🔧 fix(type): resolve ty 0.0.25 type errors PR #468
🔒 ci(workflows): add zizmor security auditing PR #467
🐛 fix(release): generate docstrfmt-compatible changelog entries PR #463

4.9.4 (2026-03-05)¶

[pre-commit.ci] pre-commit autoupdate PR #461 - by @pre-commit-ci[bot]
Update README.md
📝 docs: add project logo to documentation PR #459
Standardize .github files to .yaml suffix
build(deps): bump the all group with 2 updates PR #457 - by @dependabot[bot]
Move SECURITY.md to .github/SECURITY.md
Add permissions to workflows PR #455
Add security policy
[pre-commit.ci] pre-commit autoupdate PR #454 - by @pre-commit-ci[bot]

4.9.2 (2026-02-16)¶

📝 docs: restructure following Diataxis framework PR #448
📝 docs(platforms): fix RST formatting and TOC hierarchy PR #447

4.9.1 (2026-02-14)¶

📝 docs: enhance README, fix issues, and reorganize platforms.rst PR #445

4.9.0 (2026-02-14)¶

📚 docs: split usage guide into tutorial, how-to, and reference PR #441
✨ feat(api): add site_bin_dir property PR #443
✨ feat(api): add site_applications_dir property PR #442
🐛 fix(unix): use correct runtime dir path for OpenBSD PR #440
📝 docs(usage): document use_site_for_root parameter PR #439

4.8.0 (2026-02-14)¶

📝 docs(usage): note that home dir is in stdlib PR #431
✨ feat(api): add user_applications_dir property PR #432
✨ feat(api): add user_bin_dir property PR #430
🐛 fix(macos): yield individual site dirs in iter_*_dirs PR #429
✨ feat(windows): add WIN_PD_OVERRIDE_* env var overrides PR #428
✨ feat(windows): add PLATFORMDIRS_* env var overrides PR #427
✨ feat(api): add use_site_for_root parameter PR #426
✨ feat(api): add site_state_dir for system-wide state PR #425
✨ feat(api): add site_log_dir and document Store Python sandbox PR #424
📝 docs(windows): document Store Python sandbox path behavior PR #423

4.7.1 (2026-02-13)¶

🐛 fix(windows): avoid FileNotFoundError in sandboxed environments PR #422

4.7.0 (2026-02-12)¶

🔧 build(release): adopt filelock-style automated workflow PR #420
🐛 fix(unix): fall back to tempdir when runtime dir is not writable PR #369 - by @lengau
Replace SHGetFolderPathW with SHGetKnownFolderPath PR #380 - by @moi15moi
📝 docs: restructure and fix cross-references PR #419

4.6.0 (2026-02-12)¶

feat(macos): add XDG env var support via shared mixin PR #375 - by @Czaki
build: migrate from hatch to tox with ty PR #415
Fix docs for site_cache_dir PR #402 - by @brianhelba
Update outdated link and correct function doc PR #398 - by @joclement

4.5.1 (2025-12-05)¶

Fix no-ctypes fallback on windows PR #403 - by @youknowone

4.5.0 (2025-10-08)¶

Drop 3.9 support PR #389
Update Windows file paths in README PR #385 - by @ParadaCarleton
Add support for Python 3.14 PR #382 - by @hugovk

4.4.0 (2025-08-26)¶

feat: improve homebrew path detection PR #370 - by @daeho-ro

4.3.8 (2025-05-07)¶

Add missing examples and fix order of examples in README PR #355 - by @gene1wood

4.3.7 (2025-03-19)¶

Drop support for EOL Python 3.8 PR #330 - by @hugovk
Chunk dependabot updates into a single PR PR #311 - by @ofek

4.3.6 (2024-09-17)¶

Fix readme download target PR #307

4.3.5 (2024-09-17)¶

Split build and publish for release PR #306

4.3.4 (2024-09-17)¶

Use upstream setup-uv with uv python PR #305

4.3.3 (2024-09-13)¶

Don’t include outdated changelog in docs PR #301 - by @cbm755
Update check.yml PR #302

4.3.2 (2024-09-08)¶

Fix multi-path returned from _path methods on MacOS PR #299 - by @matthewhughes934
Use uv as installer PR #300

4.3.1 (2024-09-07)¶

Update README

4.3.0 (2024-09-07)¶

Ensure PlatformDirs is valid superclass type for mypy AND not an abstract class for other checkers PR #295 - by @Avasam
Use include-hidden-files: true to upload coverage artifacts PR #298 - by @edgarrmondragon
Test with latest PyPy PR #290 - by @edgarrmondragon
Test with Python 3.13 PR #289 - by @edgarrmondragon
Speed up Hatch installation PR #282 - by @ofek

4.2.2 (2024-05-15)¶

Fix android detection when python4android is present PR #277 - by @tmolitor-stud-tu

4.2.1 (2024-04-23)¶

Allow working without ctypes PR #275 - by @youknowone
Update dead Microsoft’s known folders documentation link PR #267 - by @deronnax
Various minor fixes PR #263 - by @deronnax
Use hatch over tox PR #262
Switch to ruff for formatting and use codespell and docformatter PR #261

4.2.0 (2024-01-31)¶

Add convenience methods to PlatformDirsAPI that allow iterating over both user and site dirs/paths PR #258 - by @SpaceshipOperations
Fix 2 typos about XDG_DATA_DIR PR #256 - by @Freed-Wu

4.1.0 (2023-12-04)¶

Drop support for EOL Python 3.7 PR #246 - by @hugovk
Fix Linux user_log_dir example in README PR #245 - by @dbohdan
Update changelog for 4.0.0 PR #242 - by @rafalkrupinski

4.0.0 (2023-11-10)¶

UNIX: revert site_cache_dir to use /var/cache instead of /var/tmp PR #239 - by @andersk

3.11.0 (2023-10-02)¶

BSD: provide a fallback for user_runtime_dir

3.10.0 (2023-07-29)¶

Add missing user media directory docs

3.9.1 (2023-07-15)¶

Have user_runtime_dir return /var/run/user/uid for *BSD

3.9.0 (2023-07-15)¶

Introduce user_downloads_dir

3.8.1 (2023-07-06)¶

Use ruff

3.8.0 (2023-06-22)¶

Test with 3.12.0.b1

3.7.0 (2023-06-20)¶

Introduce user_music_dir

3.6.0 (2023-06-18)¶

Introduce user_videos_dir

3.5.3 (2023-06-09)¶

Introduce user_pictures_dir

3.5.2 (2023-06-09)¶

Add 3.12 support
Add tox.ini to sdist
Removing Windows versions
Better handling for UNIX support

3.5.1 (2023-05-11)¶

Add auto create directories optional

3.5.0 (2023-04-27)¶

site_cache_dir use /var/tmp instead of /var/cache on unix, as the later may be write protected

3.4.0 (2023-04-26)¶

Introduce site_cache_dir

3.3.0 (2023-04-25)¶

Add appdirs keyword to package

3.2.0 (2023-03-25)¶

BREAKING Changed the config directory on macOS to point to */Library/Application Support
macOS: remove erroneous trailing slash from user_config_dir and user_data_dir

3.1.1 (2023-03-10)¶

Fix missing typing-extensions dependency

3.1.0 (2023-03-03)¶

Add detection of $PREFIX for android

3.0.1 (2023-03-02)¶

BREAKING Correct the log directory on Linux/Unix from XDG_CACHE_HOME to XDG_STATE_HOME per the XDG spec

3.0.0 (2023-02-06)¶

Fix licensing metadata
Support 3.11
Bump dependencies

2.6.2 (2022-12-28)¶

Fix missing typing-extensions dependency

2.6.1 (2022-12-29)¶

Add detection of $PREFIX for android

2.6.0 (2022-12-06)¶

BREAKING Correct the log directory on Linux/Unix from XDG_CACHE_HOME to XDG_STATE_HOME per the XDG spec

2.5.4 (2022-11-12)¶

Fix licensing metadata

2.5.3 (2022-11-06)¶

Support 3.11
Bump dependencies

2.5.2 (2022-04-18)¶

Move packaging to hatchling from setuptools
Treat android shells as unix

2.5.1 (2022-02-19)¶

Add native support for nuitka

2.5.0 (2022-02-09)¶

Add support for Termux subsystems

2.4.1 (2021-12-26)¶

Drop python 3.6 support

2.4.0 (2021-09-25)¶

Add user_documents_dir

2.3.0 (2021-08-30)¶

Add user_runtime_dir and its path-returning equivalent

2.2.0 (2021-07-29)¶

Unix: Fallback to default if XDG environment variable is empty

2.1.0 (2021-07-25)¶

Add readthedocs.org documentation via Sphinx
Modernize project layout
Drop Python 2.7 and 3.5 support
Android support
Add type annotations
Reorganize project layout to platform specific classes
Add *_path API, returning Path objects instead of str - by @papr

2.0.2 (2021-07-13)¶

Fix __version__ and __version_info__

2.0.0 (2021-07-12)¶

BREAKING Name change as part of the friendly fork
BREAKING Remove support for end-of-life Pythons 2.6, 3.2, and 3.3
BREAKING Correct the config directory on OSX/macOS
Add Python 3.7, 3.8, and 3.9 support