platformdirs

On Windows, platformdirs defaults to a two-level structure: AppData\Local\<appauthor>\<appname>. If appauthor is None, it defaults to the app name, resulting in a doubled path: AppData\Local\MyApp\MyApp.

You can control this behavior using the appauthor parameter:

• Explicit author: user_data_dir("MyApp", "AcmeCompany") $\rightarrow$ AppData\Local\AcmeCompany\MyApp.
• Flat structure: user_data_dir("MyApp", appauthor=False) $\rightarrow$ AppData\Local\MyApp.
• Default: user_data_dir("MyApp") $\rightarrow$ AppData\Local\MyApp\MyApp.

Note: appauthor is ignored on non-Windows platforms.

from platformdirs import user_data_dir

# Explicit author -- AppData\Local\AcmeCompany\MyApp
user_data_dir("MyApp", "AcmeCompany")

# No author -- AppData\Local\MyApp (flat structure)
user_data_dir("MyApp", appauthor=False)

# Default (appauthor=None) -- AppData\Local\MyApp\MyApp
user_data_dir("MyApp")

The library distinguishes between two main categories of directories:

Application Directories

These are scoped to your specific application name and version. They include both user_* (per-user, writable) and site_* (system-wide, read-only) variants where applicable.

• Data: Persistent data (user_data_dir, site_data_dir)
• Config: Configuration files (user_config_dir, site_config_dir)
• Preference: User preferences, distinct from config on macOS (user_preference_dir)
• Cache: Regeneratable cached data (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)

User Media Directories

These are standard user-facing folders that are NOT scoped to your application name.

• Standard Folders: user_documents_dir, user_downloads_dir, user_pictures_dir, user_videos_dir, user_music_dir, user_desktop_dir, user_projects_dir
• Specialty Folders: user_publicshare_dir, user_templates_dir, user_fonts_dir (writable font installation), user_bin_dir/site_bin_dir (executables), user_applications_dir/site_applications_dir

Windows directory resolution uses Shell Folder APIs. Key configuration options include:

• appauthor: By default, platformdirs adds a parent directory for the author (e.g., AppData\Local\<Author>\<App>). To avoid this and get AppData\Local\<App>, pass appauthor=False.
• roaming: Set roaming=True to switch from AppData\Local to AppData\Roaming (useful for preferences that should sync across a domain).
• Environment Overrides: Use WIN_PD_OVERRIDE_* environment variables to redirect paths (e.g., for large ML models) without changing system-wide APPDATA variables.

Handling Windows Store Python (MSIX) Sandboxing If running in a sandboxed environment, platformdirs returns the logical path. To share files with external processes, you must resolve the real on-disk path using os.path.realpath after creation.

import os
import platformdirs

data_dir = platformdirs.user_data_dir(
    appname="MyApp", appauthor="Acme", ensure_exists=True
)
# Resolve the real path for external processes
real_dir = os.path.realpath(data_dir)

Choosing a directory depends on two questions: Who owns the data? and Is the data essential?

1. Ownership

• App-internal data: Databases, caches, config files, and logs. These should be scoped to your app name using user_data_dir, user_config_dir, etc.
• User-facing data: Files the user expects to browse directly (e.g., documents, music, photos). Use media directories like user_documents_dir or user_pictures_dir which are not scoped to your app name.

2. Essentiality (for App-internal data)

• Can it be deleted without loss?
  • Yes, and it speeds things up: Use cache (e.g., API responses, thumbnails).
  • Yes, but it's temporary for this session: Use runtime (e.g., sockets, PIDs).
  • No, but it's non-critical: Use state (e.g., window positions, recent files).
• No, it is critical:
  • Settings/Options: Use config (or preference on macOS).
  • Log files: Use log.
  • Everything else: Use data (e.g., SQLite databases, user-created content).

Directories in platformdirs are categorized into User and Site variants.

User directories (user_*_dir, user_*_path)

• Per-user: Isolated for each user on the system.
• Writable: Accessible by normal users without special permissions.
• Default choice: Use these for standard application data.

Site directories (site_*_dir, site_*_path)

• System-wide: Shared across all users on the machine.
• Read-only for users: Typically requires administrator/root privileges to write.
• System defaults: Used for shared resources or by system package managers.

Pattern: Hierarchical Configuration A common pattern is to check for a site-wide default configuration first, then allow a user-specific configuration to override it.

from platformdirs import site_config_path, user_config_path

# Check site config first (system defaults), then user config (overrides)
site_cfg = site_config_path("MyApp") / "defaults.json"
user_cfg = user_config_path("MyApp") / "config.json"

if user_cfg.exists():
    config = user_cfg
elif site_cfg.exists():
    config = site_cfg
else:
    config = None