Parameter reference¶
This page documents all parameters accepted by platformdirs functions and the PlatformDirs
class.
Quick reference¶
Parameter |
Type |
Default |
Platform |
|---|---|---|---|
|
|
|
All |
|
|
|
Windows |
|
|
|
All |
|
|
|
Windows |
|
|
|
Unix/macOS |
|
|
|
All |
|
|
|
All |
|
|
|
Unix |
Details¶
appname¶
The name of your application. Used as a subdirectory in all app-specific paths. When None, the base platform
directory is returned without any app-specific subdirectory.
>>> from platformdirs import user_data_dir
>>> user_data_dir("SuperApp")
'/Users/trentm/Library/Application Support/SuperApp'
>>> user_data_dir()
'/Users/trentm/Library/Application Support'
Type: str | None
Default: None
version¶
Appends a version subdirectory. Useful for running multiple app versions side by side:
>>> from platformdirs import PlatformDirs
>>> dirs = PlatformDirs("SuperApp", "Acme", version="1.0")
>>> dirs.user_data_dir
'/Users/trentm/Library/Application Support/SuperApp/1.0'
>>> dirs.user_cache_dir
'/Users/trentm/Library/Caches/SuperApp/1.0'
Be wary of using this for configuration files; you will need to handle migrating configuration files between versions manually. See Versioned data migration for guidance.
Type: str | None
Default: None
roaming¶
Windows-only. When True, uses the roaming AppData directory (CSIDL_APPDATA) instead of the local one
(CSIDL_LOCAL_APPDATA). Roaming profiles sync across machines in a Windows domain.
>>> user_data_dir("SuperApp", "Acme", roaming=True) # on Windows
'C:\\Users\\trentm\\AppData\\Roaming\\Acme\\SuperApp'
On non-Windows platforms, this parameter is ignored.
Type: bool
Default: False
Platform: Windows only
multipath¶
Unix/macOS only. When True, site_data_dir and site_config_dir return all directories from XDG_DATA_DIRS
/ XDG_CONFIG_DIRS joined by os.pathsep (:) instead of just the first one:
>>> from platformdirs import site_data_dir
>>> site_data_dir("SuperApp", multipath=True) # on Linux
'/usr/local/share/SuperApp:/usr/share/SuperApp'
Type: bool
Default: False
Platform: Unix/macOS only
opinion¶
When True (the default), certain directories get an opinionated subdirectory. For example, on Windows the cache
directory includes a Cache subdirectory, and the log directory includes Logs. On Linux, the log directory
appends /log. Set to False to suppress this:
>>> user_cache_dir("SuperApp", "Acme") # on Windows, opinion=True
'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Cache'
>>> user_cache_dir("SuperApp", "Acme", opinion=False) # on Windows
'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp'
Type: bool
Default: True
ensure_exists¶
When True, platformdirs creates the directory a property returns, with any missing parents, each time you read it.
Defaults to False.
This applies to the data, config, cache, state, log, runtime and preference directories, user and site alike.
platformdirs creates a media directory such as user_documents_dir only when the user set it through an XDG_*_DIR
variable or user-dirs.dirs, and returns a dangling symlink there unchanged. It never creates platform defaults such
as ~/Documents, or the fonts, bin and applications directories, because the desktop session or the system owns them.
On Android the applications directory is the data directory, so platformdirs creates it too.
On Unix, macOS, iOS and Android, platformdirs creates the user directories and each missing parent with mode 0700,
as the XDG Base Directory Specification asks. Site and media
directories get the default mode so other users can read them. platformdirs leaves the mode of an existing directory
alone.
Without a resolvable home directory, ensure_exists raises RuntimeError for a path that would start with ~.
from platformdirs import PlatformDirs
dirs = PlatformDirs("SuperApp", "Acme", ensure_exists=True)
dirs.user_cache_dir # directory is created if it does not exist
Type: bool
Default: False
See also: Creating directories safely for manual directory creation patterns.
use_site_for_root¶
Unix-only. When True, redirects user_*_dir calls to their site_*_dir equivalents when running as root (uid
0). Defaults to False for backwards compatibility.
When enabled, XDG user environment variables (e.g., XDG_DATA_HOME) are bypassed for the redirected directories. This
is useful for system services running as root that should use system-wide directories rather than root’s home directory.
from platformdirs import PlatformDirs
dirs = PlatformDirs("SuperApp", use_site_for_root=True)
# When running as root, user_data_dir returns the site_data_dir path
dirs.user_data_dir # Returns site directory instead of /root/.local/share/SuperApp
Type: bool
Default: False
Platform: Unix only
XDG environment variables¶
On Linux, platformdirs follows the XDG Base Directory Specification. Environment variables like XDG_DATA_HOME,
XDG_CONFIG_HOME, XDG_CACHE_HOME, and XDG_STATE_HOME override the default directories when set.
On macOS, the same XDG environment variables are also supported and take precedence over the default macOS directories:
>>> import os
>>> os.environ["XDG_CONFIG_HOME"] = "/Users/trentm/.config"
>>> user_config_dir("SuperApp")
'/Users/trentm/.config/SuperApp'
Supported XDG variables:
XDG_DATA_HOME- user data directory.XDG_CONFIG_HOME- user config directory.XDG_CACHE_HOME- user cache directory.XDG_STATE_HOME- user state directory.XDG_DATA_DIRS- system data directories (colon-separated).XDG_CONFIG_DIRS- system config directories (colon-separated).XDG_RUNTIME_DIR- user runtime directory.
On Unix and macOS the home directory comes from HOME, or from the password database when HOME is unset or empty.
Without either, a directory under the home raises RuntimeError, while site directories and absolute XDG values still
resolve.
Windows environment variable overrides: On Windows, WIN_PD_OVERRIDE_* environment variables can override default
paths. See the Windows section for details.
Directories not covered¶
platformdirs does not provide a property for the user’s home directory. Use pathlib.Path.home() or
os.path.expanduser() from the standard library instead:
>>> from pathlib import Path
>>> Path.home()
PosixPath('/Users/trentm')