platformdirs
Cross-platform application directory locations for Python — actively maintained fork of appdirs with XDG Base Directory spec compliance. platformdirs features: PlatformDirs class, user_data_dir/user_config_dir/user_cache_dir/user_log_dir/user_runtime_dir/user_documents_dir/user_pictures_dir, site_data_dir/site_config_dir for system-wide, XDG_DATA_HOME/XDG_CONFIG_HOME/XDG_CACHE_HOME environment variable overrides on Linux, Windows roaming/non-roaming support, macOS ~/Library/* conventions, AppDirs compatibility class for appdirs drop-in replacement, and Android/Unix/Windows/macOS specific implementations.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Path utility with no network calls. User directories are user-specific — appropriate for user config storage. Validate XDG env var values if set from external sources (containers). Do not store secrets in cache_dir. Ensure permissions on created directories restrict access appropriately (chmod 700 for sensitive config dirs).
⚡ Reliability
Best When
Cross-platform Python applications needing OS-appropriate directory locations — platformdirs is the actively maintained, XDG-compliant replacement for the deprecated appdirs.
Avoid When
Temp files (use tempfile), system-wide paths requiring admin rights, or when hardcoded paths are acceptable.
Use Cases
- • Agent cross-platform config — from platformdirs import user_config_dir; config_dir = user_config_dir('MyAgent', 'MyOrg'); os.makedirs(config_dir, exist_ok=True); config_path = os.path.join(config_dir, 'config.toml') — OS-correct config path; Linux: ~/.config/MyAgent, macOS: ~/Library/Application Support/MyAgent, Windows: %APPDATA%\MyOrg\MyAgent; agent config stored correctly on all platforms
- • Agent cache management — from platformdirs import user_cache_dir; cache = user_cache_dir('MyAgent'); cache_db = os.path.join(cache, 'requests.db') — cache directory; agent HTTP cache uses OS cache location; Linux: ~/.cache/myagent, macOS: ~/Library/Caches/MyAgent; OS may reclaim cache on low disk
- • Agent XDG override support — XDG_CONFIG_HOME=/custom/path python agent.py — platformdirs respects XDG env vars on Linux; agent running in container with custom config location uses env var override; appdirs does not respect XDG_* vars; platformdirs is preferred for containerized deployments
- • Agent runtime directory — from platformdirs import user_runtime_dir; runtime_dir = user_runtime_dir('MyAgent'); socket_path = os.path.join(runtime_dir, 'agent.sock') — runtime/temp socket files; Linux: /run/user/1000/MyAgent (tmpfs, auto-cleaned); macOS/Windows: falls back to user data dir; Unix socket for agent IPC
- • Agent appdirs migration — from platformdirs import AppDirs; dirs = AppDirs('MyAgent', 'MyOrg'); dirs.user_data_dir; dirs.user_cache_dir — AppDirs compatibility class; agent code migrating from appdirs to platformdirs needs only import change; same API as appdirs.AppDirs with XDG improvements
Not For
- • Temp files — platformdirs doesn't provide temp directories; use Python's tempfile module
- • Docker without env var overrides — default paths in containers may be unexpected; set XDG_CONFIG_HOME etc. explicitly
- • System-wide directories — site_data_dir/site_config_dir require admin/root; prefer user directories
Interface
Authentication
No auth — platform directory utility library.
Pricing
platformdirs is MIT licensed. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ platformdirs does not create directories — user_data_dir() returns path string only; agent must create: os.makedirs(dirs.user_data_dir, exist_ok=True); exists_ok=True prevents error if directory already exists; most common mistake: assuming the directory exists after calling platformdirs
- ⚠ macOS does not use XDG conventions — macOS returns ~/Library/Application Support not ~/.config; XDG env vars are NOT respected on macOS; agent developers on macOS testing Linux XDG behavior must run in Linux container; test cross-platform behavior explicitly on each target OS
- ⚠ user_runtime_dir falls back on non-Linux — Linux has /run/user/UID (tmpfs cleaned on logout); macOS/Windows fall back to user_data_dir; agent using runtime_dir for sockets must handle non-tmpfs fallback; check if path is tmpfs before relying on auto-cleanup
- ⚠ Multiple app versions can conflict — PlatformDirs('MyApp', version='1.0').user_data_dir creates versioned path; PlatformDirs('MyApp', version='2.0') creates separate path; agent upgrade must migrate data between versioned directories; omit version parameter if migration is not handled
- ⚠ Windows requires appauthor for unique paths — Windows path: %APPDATA%\AppAuthor\AppName; without author: %APPDATA%\AppName\AppName; two different apps both named 'Agent' from different authors get same path without author; always provide: PlatformDirs('MyAgent', 'MyOrg') for Windows uniqueness
- ⚠ ensure_exists parameter creates directory automatically — PlatformDirs('App', ensure_exists=True).user_data_dir creates the directory on access; useful for single-call setup; but raises PermissionError immediately if parent dir not writable; agent code using ensure_exists should handle PermissionError
Alternatives
Full Evaluation Report
Comprehensive deep-dive: security analysis, reliability audit, agent experience review, cost modeling, competitive positioning, and improvement roadmap for platformdirs.
AI-powered analysis · PDF + markdown · Delivered within 30 minutes
Package Brief
Quick verdict, integration guide, cost projections, gotchas with workarounds, and alternatives comparison.
Delivered within 10 minutes
Score Monitoring
Get alerted when this package's AF, security, or reliability scores change significantly. Stay ahead of regressions.
Continuous monitoring
Scores are editorial opinions as of 2026-03-06.