Changelog¶

Unreleased (2026-07-21)¶

4.11.0 (2026-07-21)¶

Declare support for Python 3.15 and run the test suite against it, currently in beta. PR #512

4.10.1 (2026-07-18)¶

Stop leaking memory on repeated Windows folder lookups. get_win_folder_via_ctypes defined a fresh ctypes structure on every call, and each one registered a pointer type that was never released; the resolver is now built once and reused. PR #507

4.10.0 (2026-05-28)¶

Add user_publicshare_dir(), user_templates_dir(), user_fonts_dir(), and user_preference_dir() PR #491
Add user_projects_dir() backed by $XDG_PROJECTS_DIR PR #490
Return only the first path from site_config_path() on macOS when multipath is set PR #488 - by @lphuc2250gma

4.9.6 (2026-04-09)¶

Fix macOS XDG variables leaking across user_config_dir(), user_data_dir(), and user_state_dir() when only some are set PR #473 - by @Goddesen
Avoid duplicate site directories in Unix iter_config_dirs() and iter_data_dirs() when use_site_for_root is active PR #469 - by @viccie30

4.9.4 (2026-03-05)¶

Respect XDG_CONFIG_HOME when reading the user-dirs configuration PR #453 - by @bysiber
Create the directory in Android user_log_dir() and user_runtime_dir() when ensure_exists is set PR #452 - by @bysiber

4.9.2 (2026-02-16)¶

No user-facing changes

4.9.1 (2026-02-14)¶

No user-facing changes

4.9.0 (2026-02-14)¶

Add site_bin_dir() PR #443
Add site_applications_dir() PR #442
Use the correct runtime directory path on OpenBSD PR #440

4.8.0 (2026-02-14)¶

Add use_site_for_root to redirect user_*_dir to site_*_dir for root on Unix PR #426
Add site_state_dir() for system-wide state PR #425
Add site_log_dir() PR #424
Add user_applications_dir() PR #432
Add user_bin_dir() PR #430
Add PLATFORMDIRS_* environment variable overrides for Windows folder resolution PR #427
Add WIN_PD_OVERRIDE_* environment variable overrides for Windows folder resolution PR #428
Yield individual site directories from iter_data_dirs() and iter_config_dirs() on macOS PR #429

4.7.1 (2026-02-13)¶

Avoid FileNotFoundError on Windows in sandboxed environments PR #422

4.7.0 (2026-02-12)¶

Fall back to a temp directory when the Unix runtime dir is not writable PR #369 - by @lengau
Use SHGetKnownFolderPath instead of the deprecated SHGetFolderPathW on Windows PR #380 - by @moi15moi

4.6.0 (2026-02-12)¶

Honor XDG environment variables on macOS PR #375 - by @Czaki
Fix site_cache_dir() documentation PR #402 - by @brianhelba
Fix an outdated link and correct a function docstring 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)¶

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

4.4.0 (2025-08-26)¶

Improve Homebrew path detection PR #370 - by @daeho-ro

4.3.8 (2025-05-07)¶

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

4.3.7 (2025-03-19)¶

Drop support for EOL Python 3.8 PR #330 - by @hugovk

4.3.6 (2024-09-17)¶

No user-facing changes

4.3.5 (2024-09-17)¶

No user-facing changes

4.3.4 (2024-09-17)¶

No user-facing changes

4.3.3 (2024-09-13)¶

No user-facing changes

4.3.2 (2024-09-08)¶

Fix multi-path returned from _path methods on macOS PR #299 - by @matthewhughes934

4.3.1 (2024-09-07)¶

No user-facing changes

4.3.0 (2024-09-07)¶

Make PlatformDirs usable as a mypy superclass without breaking other type checkers PR #295 - by @Avasam
Add support for Python 3.13 PR #289 - by @edgarrmondragon

4.2.2 (2024-05-15)¶

Fix Android detection when python-for-android is present PR #277 - by @tmolitor-stud-tu

4.2.1 (2024-04-23)¶

Allow working without ctypes PR #275 - by @youknowone

4.2.0 (2024-01-31)¶

Add convenience methods to iterate over both user and site dirs and paths PR #258 - by @SpaceshipOperations
Fix two typos referencing 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

4.0.0 (2023-11-10)¶

Revert site_cache_dir() on UNIX to /var/cache instead of /var/tmp PR #239 - by @andersk

3.11.0 (2023-10-02)¶

Detect Homebrew-installed software on macOS PR #232 - by @singingwolfboy

3.10.0 (2023-07-29)¶

Add site_runtime_dir() PR #212 - by @kemzeb

3.9.1 (2023-07-15)¶

Optionally create the opinionated log subdirectory in user_log_dir() on Unix PR #208 - by @kemzeb

3.9.0 (2023-07-15)¶

Add user_desktop_dir() and user_desktop_path() PR #200 - by @lukacat10

3.8.1 (2023-07-06)¶

Provide a fallback for user_runtime_dir() on BSD PR #201 - by @RayyanAnsari

3.8.0 (2023-06-22)¶

No user-facing changes

3.7.0 (2023-06-20)¶

Return /var/run/user/$uid from user_runtime_dir() on *BSD PR #194 - by @kemzeb

3.6.0 (2023-06-18)¶

Add user_downloads_dir() PR #192 - by @cofiem

3.5.3 (2023-06-09)¶

Add support for Python 3.12

3.5.2 (2023-06-09)¶

No user-facing changes

3.5.1 (2023-05-11)¶

Define getuid on all non-Windows platforms so user_runtime_dir() works beyond Linux PR #183

3.5.0 (2023-04-27)¶

Add user_music_dir() PR #173 - by @kemzeb

3.4.0 (2023-04-26)¶

Add user_videos_dir() PR #169 - by @kemzeb

3.3.0 (2023-04-25)¶

Add user_pictures_dir() PR #167 - by @kemzeb

3.2.0 (2023-03-25)¶

Add the ensure_exists option to create directories when they are missing PR #155 - by @smsearcy

3.1.1 (2023-03-10)¶

Point site_cache_dir() at /var/tmp instead of write-protected /var/cache on Unix PR #148 - by @efiop

3.1.0 (2023-03-03)¶

Add site_cache_dir() PR #145 - by @efiop

3.0.0 (2023-02-06)¶

BREAKING Point macOS user_config_dir() and site_config_dir() at */Library/Application Support to mirror the data dirs, and drop the trailing slash from user_config_dir() and user_data_dir() PR #137 - by @ThomasWaldmann

2.6.2 (2022-12-28)¶

Add typing-extensions as a dependency on Python < 3.8 PR #123 - by @amacf

2.6.1 (2022-12-29)¶

Detect Termux via $PREFIX when $SHELL is unset PR #115 - by @Freed-Wu

2.6.0 (2022-12-06)¶

Point user_log_dir() at user_state_dir() on Linux per the XDG spec PR #108 - by @lordwelch

2.5.4 (2022-11-12)¶

No user-facing changes

2.5.3 (2022-11-06)¶

Declare support for Python 3.11 PR #103 - by @hugovk

2.5.2 (2022-04-18)¶

Treat Android shells as Unix PR #72

2.5.1 (2022-02-19)¶

Work out of the box under Nuitka standalone builds PR #68

2.5.0 (2022-02-09)¶

Support the Termux subsystem PR #63 - by @YariKartoshe4ka

2.4.1 (2021-12-26)¶

BREAKING Drop Python 3.6 support PR #52

2.4.0 (2021-09-25)¶

Add user_documents_dir() PR #39 - by @JuneStepp

2.3.0 (2021-08-30)¶

Add user_runtime_dir() for $XDG_RUNTIME_DIR PR #37 - by @whonore

2.2.0 (2021-07-29)¶

Unix: fall back to the default when the $XDG_* environment variable is empty PR #30 - by @papr

2.1.0 (2021-07-25)¶

Add pathlib.Path-returning *_path API alongside the string variants PR #27 - by @papr
Add Android support PR #18
Add type annotations PR #20 - by @domdfcoding
BREAKING Drop Python 2.7 and 3.5 support PR #14 - by @domdfcoding

2.0.2 (2021-07-13)¶

No user-facing changes

2.0.0 (2021-07-12)¶

BREAKING Rename appdirs to platformdirs 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 macOS
Add support for Python 3.7, 3.8, and 3.9