API¶

User directories¶

These are user-specific (and, generally, user-writeable) directories.

User data directory¶

User config directory¶

User cache directory¶

User state directory¶

User log directory¶

User runtime directory¶

User applications directory¶

User binary directory¶

User documents directory¶

User downloads directory¶

User pictures directory¶

User videos directory¶

User music directory¶

User desktop directory¶

User projects directory¶

User templates directory¶

User fonts directory¶

User preference directory¶

Shared directories¶

These are system-wide (and, generally, read-only) directories.

Shared data directory¶

Shared config directory¶

Shared cache directory¶

Shared state directory¶

Shared log directory¶

Shared runtime directory¶

Shared applications directory¶

Shared binary directory¶

Iterator methods¶

These methods are available on PlatformDirs instances. They yield both user and site directories for a given type, enabling configuration merging and fallback patterns. See Merging config from multiple sources for a practical example. The most specific directory comes first, and each distinct directory appears once.

iter_data_dirs() / iter_data_paths()
iter_config_dirs() / iter_config_paths()
iter_cache_dirs() / iter_cache_paths()
iter_state_dirs() / iter_state_paths()
iter_log_dirs() / iter_log_paths()
iter_runtime_dirs() / iter_runtime_paths()

See PlatformDirsABC for the full method documentation.

Testing¶

See Testing code that uses platformdirs for examples.

platformdirs.testing.isolated_dirs(root)[source]¶

Resolve every directory of PlatformDirs under root while the context is active.

Each kind maps to <root>/<kind>, where kind is the property name without _dir, such as user_config. The data, config, cache, state, log, runtime and preference kinds append appname and version, so PlatformDirs("app", version="1.0").user_config_path becomes <root>/user_config/app/1.0. Every thread of the current process sees the change, and subprocesses do not.

Parameters:: root (str | PathLike[str]) – directory that holds the redirected directories
Return type:: Iterator[Path]
Returns:: root as a Path

The platformdirs_isolated pytest fixture runs a test inside isolated_dirs(tmp_path) and yields the root. platformdirs registers it through the pytest11 entry point, and a test gets it only by requesting it.

Backwards compatibility¶

AppDirs is an alias for PlatformDirs, provided for backwards compatibility with the appdirs package:

from platformdirs import AppDirs

dirs = AppDirs("MyApp", "Acme")  # equivalent to PlatformDirs("MyApp", "Acme")

Platforms¶

ABC¶

class platformdirs.api.PlatformDirsABC(appname=None, appauthor=None, version=None, roaming=False, multipath=False, opinion=True, ensure_exists=False, use_site_for_root=False)[source]¶

Bases: ABC

Abstract base class defining all platform directory properties, their Path variants, and iterators.

Platform-specific subclasses (e.g. Windows, MacOS, Unix) implement the abstract properties to return the appropriate paths for each operating system.

__init__(appname=None, appauthor=None, version=None, roaming=False, multipath=False, opinion=True, ensure_exists=False, use_site_for_root=False)[source]¶

Create a new platform directory.

Parameters:

appname (str | None) – See appname.
appauthor (str | Literal[False] | None) – See appauthor.
version (str | None) – See version.
roaming (bool) – See roaming.
multipath (bool) – See multipath.
opinion (bool) – See opinion.
ensure_exists (bool) – See ensure_exists.
use_site_for_root (bool) – See use_site_for_root.

roaming¶

Whether to use the roaming appdata directory on Windows.

That means that for users on a Windows network setup for roaming profiles, this user data will be synced on login (see here).

multipath¶

An optional parameter which indicates that the entire list of data dirs should be returned.

When False, only the first item is returned. Affects site_data_dir, site_config_dir and site_applications_dir on Unix and macOS, and site_cache_dir on macOS under Homebrew.

opinion¶

Whether to use opinionated values.

When enabled, appends an additional subdirectory for certain directories: e.g. Cache for cache and Logs for logs on Windows, log for logs on Unix.

ensure_exists¶

Create the directory a property returns, with missing parents, each time the property is read.

Media directories qualify only when the user set them through XDG. platformdirs never creates fonts, bin, applications or default media directories. Off by default.

use_site_for_root¶

Whether to redirect user_*_dir calls to their site_*_dir equivalents when running as root (uid 0).

Only has an effect on Unix. Disabled by default for backwards compatibility. When enabled, XDG user environment variables (e.g. XDG_DATA_HOME) are bypassed for the redirected directories.

property appname¶: The name of the application.

property appauthor¶

The name of the app author or distributing body for this application.

Typically, it is the owning company name. Defaults to appname. You may pass False to disable it.

Note

On Windows, the directory structure is <base>/<appauthor>/<appname>. When appauthor is None (the default), it falls back to appname, resulting in <base>/<appname>/<appname> (e.g. AppData/Local/myapp/myapp). Pass appauthor=False to omit the author directory entirely and get <base>/<appname>.

property version¶

An optional version path element to append to the path.

You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be <major>.<minor>.

abstract property user_data_dir¶: Data directory tied to the user.

abstract property site_data_dir¶: Data directory shared by users.

abstract property user_config_dir¶: Config directory tied to the user.

abstract property site_config_dir¶: Config directory shared by users.

abstract property user_cache_dir¶: Cache directory tied to the user.

abstract property site_cache_dir¶: Cache directory shared by users.

abstract property user_state_dir¶: State directory tied to the user.

abstract property site_state_dir¶: State directory shared by users.

abstract property user_log_dir¶: Log directory tied to the user.

abstract property site_log_dir¶: Log directory shared by users.

abstract property user_documents_dir¶: Documents directory tied to the user.

abstract property user_downloads_dir¶: Downloads directory tied to the user.

abstract property user_pictures_dir¶: Pictures directory tied to the user.

abstract property user_videos_dir¶: Videos directory tied to the user.

abstract property user_music_dir¶: Music directory tied to the user.

abstract property user_desktop_dir¶: Desktop directory tied to the user.

abstract property user_projects_dir¶: Projects directory tied to the user.

abstract property user_publicshare_dir¶: Public share directory tied to the user.

abstract property user_templates_dir¶: Templates directory tied to the user.

abstract property user_fonts_dir¶: Fonts directory tied to the user.

abstract property user_preference_dir¶: Preference directory tied to the user.

abstract property user_bin_dir¶: Bin directory tied to the user.

abstract property site_bin_dir¶: Bin directory shared by users.

abstract property user_applications_dir¶: Applications directory tied to the user.

abstract property site_applications_dir¶: Applications directory shared by users.

abstract property user_runtime_dir¶: Runtime directory tied to the user.

abstract property site_runtime_dir¶: Runtime directory shared by users.

property user_data_path¶: Data path tied to the user.

property site_data_path¶: Data path shared by users. Only return the first item, even if multipath is set to True.

property user_config_path¶: Config path tied to the user.

property site_config_path¶: Config path shared by users. Only return the first item, even if multipath is set to True.

property user_cache_path¶: Cache path tied to the user.

property site_cache_path¶: Cache path shared by users. Only return the first item, even if multipath is set to True.

property user_state_path¶: State path tied to the user.

property site_state_path¶: State path shared by users.

property user_log_path¶: Log path tied to the user.

property site_log_path¶: Log path shared by users.

property user_documents_path¶: Documents path tied to the user.

property user_downloads_path¶: Downloads path tied to the user.

property user_pictures_path¶: Pictures path tied to the user.

property user_videos_path¶: Videos path tied to the user.

property user_music_path¶: Music path tied to the user.

property user_desktop_path¶: Desktop path tied to the user.

property user_projects_path¶: Projects path tied to the user.

property user_publicshare_path¶: Public share path tied to the user.

property user_templates_path¶: Templates path tied to the user.

property user_fonts_path¶: Fonts path tied to the user.

property user_preference_path¶: Preference path tied to the user.

property user_bin_path¶: Bin path tied to the user.

property site_bin_path¶: Bin path shared by users.

property user_applications_path¶: Applications path tied to the user.

property site_applications_path¶: Applications path shared by users. Only return the first item, even if multipath is set to True.

property user_runtime_path¶: Runtime path tied to the user.

property site_runtime_path¶: Runtime path shared by users.

iter_config_dirs()[source]¶

Yield:: all user and site configuration directories.

iter_data_dirs()[source]¶

Yield:: all user and site data directories.

iter_cache_dirs()[source]¶

Yield:: all user and site cache directories.

iter_state_dirs()[source]¶

Yield:: all user and site state directories.

iter_log_dirs()[source]¶

Yield:: all user and site log directories.

iter_runtime_dirs()[source]¶

Yield:: all user and site runtime directories.

iter_config_paths()[source]¶

Yield:: all user and site configuration paths.

iter_data_paths()[source]¶

Yield:: all user and site data paths.

iter_cache_paths()[source]¶

Yield:: all user and site cache paths.

iter_state_paths()[source]¶

Yield:: all user and site state paths.

iter_log_paths()[source]¶

Yield:: all user and site log paths.

iter_runtime_paths()[source]¶

Yield:: all user and site runtime paths.

place_config_file(name)[source]¶

Return the path of name under user_config_path, creating the missing directories on the way.

Each directory it creates, including the user directory itself, gets mode 0o700 whether or not ensure_exists is set; directories that already exist keep their mode. It does not create the file.

Parameters:

name (str | PathLike[str]) – file path relative to the user directory, e.g. "sub/app.toml".

Raises:

ValueError – if name is empty, absolute, has a drive or climbs out through ...
RuntimeError – if the user directory starts with ~ because the home directory is unknown.

Return type:

Path

place_data_file(name)[source]¶

Like place_config_file, under user_data_path.

Return type:: Path

place_cache_file(name)[source]¶

Like place_config_file, under user_cache_path.

Return type:: Path

place_state_file(name)[source]¶

Like place_config_file, under user_state_path.

Return type:: Path

place_log_file(name)[source]¶

Like place_config_file, under user_log_path.

Return type:: Path

place_runtime_file(name)[source]¶

Like place_config_file, under user_runtime_path.

Raises:: PermissionError – on Unix, if another user owns the temporary fallback directory.
Return type:: Path

find_config_file(name)[source]¶

Find the first name file in iter_config_paths() order, without creating any directory.

Parameters:: name (str | PathLike[str]) – path relative to each directory, may contain subdirectories.
Return type:: Path | None
Returns:: the file, or None when no directory holds one.
Raises:: ValueError – if name is absolute, has a drive or climbs out with ...

find_config_files(name)[source]¶

Find every name file in iter_config_paths() order, without creating any directory.

Parameters:: name (str | PathLike[str]) – see find_config_file().
Return type:: list[Path]
Returns:: the files, user directory first.
Raises:: ValueError – see find_config_file().

find_data_file(name)[source]¶

Like find_config_file(), searching iter_data_paths().

Return type:: Path | None

find_data_files(name)[source]¶

Like find_config_files(), searching iter_data_paths().

Return type:: list[Path]

find_cache_file(name)[source]¶

Like find_config_file(), searching iter_cache_paths().

Return type:: Path | None

find_cache_files(name)[source]¶

Like find_config_files(), searching iter_cache_paths().

Return type:: list[Path]

find_state_file(name)[source]¶

Like find_config_file(), searching iter_state_paths().

Return type:: Path | None

find_state_files(name)[source]¶

Like find_config_files(), searching iter_state_paths().

Return type:: list[Path]

find_log_file(name)[source]¶

Like find_config_file(), searching iter_log_paths().

Return type:: Path | None

find_log_files(name)[source]¶

Like find_config_files(), searching iter_log_paths().

Return type:: list[Path]

find_runtime_file(name)[source]¶

Like find_config_file(), searching iter_runtime_paths().

Return type:: Path | None

find_runtime_files(name)[source]¶

Like find_config_files(), searching iter_runtime_paths().

Return type:: list[Path]

PlatformDirs¶

platformdirs.PlatformDirs¶: Currently active platform

Android¶

class platformdirs.android.Android(appname=None, appauthor=None, version=None, roaming=False, multipath=False, opinion=True, ensure_exists=False, use_site_for_root=False)[source]¶

Bases: PlatformDirsABC

Platform directories for Android.

Follows the guidance from here. Directories are typically located under the app’s private storage (/data/user/<userid>/<packagename>/).

Makes use of the appname, version, opinion, ensure_exists.

property user_data_dir¶: Data directory tied to the user, e.g. /data/user/<userid>/<packagename>/files/<AppName>.

property site_data_dir¶: Data directory shared by users, same as user_data_dir.

property user_config_dir¶: Config directory tied to the user, e.g. /data/user/<userid>/<packagename>/shared_prefs/<AppName>.

property site_config_dir¶: Config directory shared by users, same as user_config_dir.

property user_cache_dir¶: Cache directory tied to the user, e.g.,``/data/user/<userid>/<packagename>/cache/<AppName>``.

property site_cache_dir¶: Cache directory shared by users, same as user_cache_dir.

property user_state_dir¶: State directory tied to the user, same as user_data_dir.

property site_state_dir¶: State directory shared by users, same as user_state_dir.

property user_log_dir¶: Log directory tied to the user, same as user_cache_dir if not opinionated else log in it, e.g. /data/user/<userid>/<packagename>/cache/<AppName>/log.

property site_log_dir¶: Log directory shared by users, same as user_log_dir.

property user_documents_dir¶: Documents directory tied to the user e.g. /storage/emulated/0/Documents.

property user_downloads_dir¶: Downloads directory tied to the user e.g. /storage/emulated/0/Download.

property user_pictures_dir¶: Pictures directory tied to the user e.g. /storage/emulated/0/Pictures.

property user_videos_dir¶: Videos directory tied to the user e.g. /storage/emulated/0/Movies.

property user_music_dir¶: Music directory tied to the user e.g. /storage/emulated/0/Music.

property user_desktop_dir¶: Desktop directory tied to the user e.g. /storage/emulated/0/Documents/Desktop.

property user_projects_dir¶: Projects directory tied to the user e.g. /storage/emulated/0/Documents/Projects.

property user_publicshare_dir¶: Public share directory tied to the user e.g. /storage/emulated/0/Documents/Public.

property user_templates_dir¶: Templates directory tied to the user e.g. /storage/emulated/0/Documents/Templates.

property user_fonts_dir¶: Fonts directory tied to the user e.g. /storage/emulated/0/Documents/fonts.

property user_preference_dir¶: Preference directory tied to the user, same as user_config_dir.

property user_bin_dir¶: Bin directory tied to the user, e.g. /data/user/<userid>/<packagename>/files/bin.

property site_bin_dir¶: Bin directory shared by users, same as user_bin_dir.

property user_applications_dir¶: Applications directory tied to the user, same as user_data_dir.

property site_applications_dir¶: Applications directory shared by users, same as user_applications_dir.

property user_runtime_dir¶: Runtime directory tied to the user, same as user_cache_dir if not opinionated else tmp in it, e.g. /data/user/<userid>/<packagename>/cache/<AppName>/tmp.

property site_runtime_dir¶: Runtime directory shared by users, same as user_runtime_dir.

iOS¶

class platformdirs.ios.IOS(appname=None, appauthor=None, version=None, roaming=False, multipath=False, opinion=True, ensure_exists=False, use_site_for_root=False)[source]¶

Bases: PlatformDirsABC

Platform directories for iOS and iPadOS.

Follows the app container layout from Apple’s File System Programming Guide. On iOS the home directory is the app’s sandbox, so ~ below is the app’s data container. An app has no system-wide directories, so each site_*_dir returns its user_*_dir.

Makes use of the appname, version, ensure_exists.

property user_data_dir¶: Data directory tied to the user, e.g. ~/Library/Application Support/$appname/$version.

property site_data_dir¶: Data directory shared by users, same as user_data_dir.

property user_config_dir¶: Config directory tied to the user, same as user_data_dir.

property site_config_dir¶: Config directory shared by users, same as user_config_dir.

property user_cache_dir¶: Cache directory tied to the user, e.g. ~/Library/Caches/$appname/$version.

property site_cache_dir¶: Cache directory shared by users, same as user_cache_dir.

property user_state_dir¶: State directory tied to the user, same as user_data_dir.

property site_state_dir¶: State directory shared by users, same as user_state_dir.

property user_log_dir¶: Log directory tied to the user, e.g. ~/Library/Logs/$appname/$version.

property site_log_dir¶: Log directory shared by users, same as user_log_dir.

property user_documents_dir¶: Documents directory tied to the user, e.g. ~/Documents.

property user_downloads_dir¶: Downloads directory tied to the user, e.g. ~/Documents/Downloads.

property user_pictures_dir¶: Pictures directory tied to the user, e.g. ~/Documents/Pictures.

property user_videos_dir¶: Videos directory tied to the user, e.g. ~/Documents/Movies.

property user_music_dir¶: Music directory tied to the user, e.g. ~/Documents/Music.

property user_desktop_dir¶: Desktop directory tied to the user, e.g. ~/Documents/Desktop.

property user_projects_dir¶: Projects directory tied to the user, e.g. ~/Documents/Projects.

property user_publicshare_dir¶: Public share directory tied to the user, e.g. ~/Documents/Public.

property user_templates_dir¶: Templates directory tied to the user, e.g. ~/Documents/Templates.

property user_fonts_dir¶: Fonts directory tied to the user, e.g. ~/Library/Fonts.

property user_preference_dir¶: Preference directory tied to the user, same as user_config_dir.

property user_bin_dir¶: Bin directory tied to the user, e.g. ~/.local/bin.

property site_bin_dir¶: Bin directory shared by users, same as user_bin_dir.

property user_applications_dir¶: Applications directory tied to the user, e.g. ~/Applications.

property site_applications_dir¶: Applications directory shared by users, same as user_applications_dir.

property user_runtime_dir¶: Runtime directory tied to the user, e.g. ~/tmp/$appname/$version.

property site_runtime_dir¶: Runtime directory shared by users, same as user_runtime_dir.

macOS¶

class platformdirs.macos.MacOS(appname=None, appauthor=None, version=None, roaming=False, multipath=False, opinion=True, ensure_exists=False, use_site_for_root=False)[source]¶

Bases: XDGMixin, _MacOSDefaults

Platform directories for the macOS operating system.

Follows the guidance from Apple documentation. Makes use of the appname, version, ensure_exists.

XDG environment variables (e.g. $XDG_DATA_HOME) are supported and take precedence over macOS defaults.

Unix (Linux)¶

class platformdirs.unix.Unix(appname=None, appauthor=None, version=None, roaming=False, multipath=False, opinion=True, ensure_exists=False, use_site_for_root=False)[source]¶

Bases: XDGMixin, _UnixDefaults

On Unix/Linux, we follow the XDG Basedir Spec.

The spec allows overriding directories with environment variables. The examples shown are the default values, alongside the name of the environment variable that overrides them. Makes use of the appname, version, multipath, opinion, ensure_exists.

property user_data_dir¶: Data directory tied to the user, or site equivalent when root with use_site_for_root.

property user_config_dir¶: Config directory tied to the user, or site equivalent when root with use_site_for_root.

property user_cache_dir¶: Cache directory tied to the user, or site equivalent when root with use_site_for_root.

property user_state_dir¶: State directory tied to the user, or site equivalent when root with use_site_for_root.

property user_log_dir¶: Log directory tied to the user, or site equivalent when root with use_site_for_root.

property user_applications_dir¶: Applications directory tied to the user, or site equivalent when root with use_site_for_root.

property user_runtime_dir¶

Runtime directory tied to the user, e.g. $XDG_RUNTIME_DIR/$appname/$version.

Accepts $XDG_RUNTIME_DIR only as a directory, not a symlink, that the user owns with mode 0700, as the XDG spec requires, and creates a missing one that way under ensure_exists. When the variable is unset or fails that check, emits one RuntimeDirWarning per cause and falls back to the platform default (/tmp/run/user/<uid> on OpenBSD, /var/run/user/<uid> on FreeBSD/NetBSD, /run/user/<uid> elsewhere) if it passes the same check, else to runtime-<uid> in the temporary directory. Root with use_site_for_root gets the site equivalent.

Raises:: PermissionError – if the temporary fallback is a symlink, not a directory, or owned by another user.

property user_bin_dir¶: Bin directory tied to the user, or site equivalent when root with use_site_for_root.

property user_data_path¶: Data path tied to the user, or the first site entry when root with use_site_for_root.

property user_config_path¶: Config path tied to the user, or the first site entry when root with use_site_for_root.

property user_preference_path¶: Preference path tied to the user, or the first site config entry when root with use_site_for_root.

property user_applications_path¶: Applications path tied to the user, or the first site entry when root with use_site_for_root.

exception platformdirs.RuntimeDirWarning[source]¶

Bases: UserWarning

Emitted when the Unix user_runtime_dir cannot use $XDG_RUNTIME_DIR.

Windows¶

class platformdirs.windows.Windows(appname=None, appauthor=None, version=None, roaming=False, multipath=False, opinion=True, ensure_exists=False, use_site_for_root=False)[source]¶

Bases: PlatformDirsABC

MSDN on where to store app data files.

Makes use of the appname, appauthor, version, roaming, opinion, ensure_exists.

property user_data_dir¶: Data directory tied to the user, e.g. %USERPROFILE%\AppData\Local\$appauthor\$appname (not roaming) or %USERPROFILE%\AppData\Roaming\$appauthor\$appname (roaming).

property site_data_dir¶: Data directory shared by users, e.g. C:\ProgramData\$appauthor\$appname.

property user_config_dir¶: Config directory tied to the user, same as user_data_dir.

property site_config_dir¶: Config directory shared by users, same as site_data_dir.

property user_cache_dir¶: Cache directory tied to the user (if opinionated with Cache folder within $appname) e.g. %USERPROFILE%\AppData\Local\$appauthor\$appname\Cache\$version.

property site_cache_dir¶: Cache directory shared by users, e.g. C:\ProgramData\$appauthor\$appname\Cache\$version.

property user_state_dir¶: State directory tied to the user, same as user_data_dir.

property site_state_dir¶: State directory shared by users, same as site_data_dir.

property user_log_dir¶: Log directory tied to the user, same as user_data_dir if not opinionated else Logs in it.

property site_log_dir¶: Log directory shared by users, same as site_data_dir if not opinionated else Logs in it.

property user_documents_dir¶: Documents directory tied to the user e.g. %USERPROFILE%\Documents.

property user_downloads_dir¶: Downloads directory tied to the user e.g. %USERPROFILE%\Downloads.

property user_pictures_dir¶: Pictures directory tied to the user e.g. %USERPROFILE%\Pictures.

property user_videos_dir¶: Videos directory tied to the user e.g. %USERPROFILE%\Videos.

property user_music_dir¶: Music directory tied to the user e.g. %USERPROFILE%\Music.

property user_desktop_dir¶: Desktop directory tied to the user, e.g. %USERPROFILE%\Desktop.

property user_projects_dir¶: Projects directory tied to the user, e.g. %USERPROFILE%\Projects.

property user_publicshare_dir¶: Public share directory e.g. C:\Users\Public.

property user_templates_dir¶: Templates directory tied to the user e.g. %APPDATA%\Microsoft\Windows\Templates.

property user_fonts_dir¶: Fonts directory tied to the user e.g. %LOCALAPPDATA%\Microsoft\Windows\Fonts.

property user_preference_dir¶: Preference directory tied to the user, same as user_config_dir.

property user_bin_dir¶: Bin directory tied to the user, e.g. %LOCALAPPDATA%\Programs.

property site_bin_dir¶: Bin directory shared by users, e.g. C:\ProgramData\bin.

property user_applications_dir¶: Applications directory tied to the user, e.g. Start Menu\Programs.

property site_applications_dir¶: Applications directory shared by users, e.g. C:\ProgramData\Microsoft\Windows\Start Menu\Programs.

property user_runtime_dir¶: Runtime directory tied to the user, e.g. %USERPROFILE%\AppData\Local\Temp\$appauthor\$appname.

property site_runtime_dir¶: Runtime directory shared by users, same as user_runtime_dir.

API¶

User directories¶

User data directory¶

User config directory¶

User cache directory¶

User state directory¶

User log directory¶

User runtime directory¶

User applications directory¶

User binary directory¶

User documents directory¶

User downloads directory¶

User pictures directory¶

User videos directory¶

User music directory¶

User desktop directory¶

User projects directory¶

User public share directory¶

User templates directory¶

User fonts directory¶

User preference directory¶

Shared directories¶

Shared data directory¶

Shared config directory¶

Shared cache directory¶

Shared state directory¶

Shared log directory¶

Shared runtime directory¶

Shared applications directory¶

Shared binary directory¶

Iterator methods¶

Testing¶

Backwards compatibility¶

Platforms¶

ABC¶

PlatformDirs¶

Android¶

iOS¶

macOS¶

Unix (Linux)¶

Windows¶