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.

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.

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.

appname¶: The name of the application.

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>.

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>.

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.

By default, the first item would only be returned. Only affects site_data_dir and site_config_dir on Unix and macOS.

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¶

Optionally create the directory (and any missing parents) upon access if it does not exist.

By default, no directories are created.

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.

abstract property user_data_dir¶

Returns:: data directory tied to the user

abstract property site_data_dir¶

Returns:: data directory shared by users

abstract property user_config_dir¶

Returns:: config directory tied to the user

abstract property site_config_dir¶

Returns:: config directory shared by users

abstract property user_cache_dir¶

Returns:: cache directory tied to the user

abstract property site_cache_dir¶

Returns:: cache directory shared by users

abstract property user_state_dir¶

Returns:: state directory tied to the user

abstract property site_state_dir¶

Returns:: state directory shared by users

abstract property user_log_dir¶

Returns:: log directory tied to the user

abstract property site_log_dir¶

Returns:: log directory shared by users

abstract property user_documents_dir¶

Returns:: documents directory tied to the user

abstract property user_downloads_dir¶

Returns:: downloads directory tied to the user

abstract property user_pictures_dir¶

Returns:: pictures directory tied to the user

abstract property user_videos_dir¶

Returns:: videos directory tied to the user

abstract property user_music_dir¶

Returns:: music directory tied to the user

abstract property user_desktop_dir¶

Returns:: desktop directory tied to the user

abstract property user_projects_dir¶

Returns:: projects directory tied to the user

abstract property user_publicshare_dir¶

Returns:: public share directory tied to the user

abstract property user_templates_dir¶

Returns:: templates directory tied to the user

abstract property user_fonts_dir¶

Returns:: fonts directory tied to the user

abstract property user_preference_dir¶

Returns:: preference directory tied to the user

abstract property user_bin_dir¶

Returns:: bin directory tied to the user

abstract property site_bin_dir¶

Returns:: bin directory shared by users

abstract property user_applications_dir¶

Returns:: applications directory tied to the user

abstract property site_applications_dir¶

Returns:: applications directory shared by users

abstract property user_runtime_dir¶

Returns:: runtime directory tied to the user

abstract property site_runtime_dir¶

Returns:: runtime directory shared by users

property user_data_path¶

Returns:: data path tied to the user

property site_data_path¶

Returns:: data path shared by users

property user_config_path¶

Returns:: config path tied to the user

property site_config_path¶

Returns:: config path shared by users

property user_cache_path¶

Returns:: cache path tied to the user

property site_cache_path¶

Returns:: cache path shared by users

property user_state_path¶

Returns:: state path tied to the user

property site_state_path¶

Returns:: state path shared by users

property user_log_path¶

Returns:: log path tied to the user

property site_log_path¶

Returns:: log path shared by users

property user_documents_path¶

Returns:: documents path tied to the user

property user_downloads_path¶

Returns:: downloads path tied to the user

property user_pictures_path¶

Returns:: pictures path tied to the user

property user_videos_path¶

Returns:: videos path tied to the user

property user_music_path¶

Returns:: music path tied to the user

property user_desktop_path¶

Returns:: desktop path tied to the user

property user_projects_path¶

Returns:: projects path tied to the user

property user_publicshare_path¶

Returns:: public share path tied to the user

property user_templates_path¶

Returns:: templates path tied to the user

property user_fonts_path¶

Returns:: fonts path tied to the user

property user_preference_path¶

Returns:: preference path tied to the user

property user_bin_path¶

Returns:: bin path tied to the user

property site_bin_path¶

Returns:: bin path shared by users

property user_applications_path¶

Returns:: applications path tied to the user

property site_applications_path¶

Returns:: applications path shared by users

property user_runtime_path¶

Returns:: runtime path tied to the user

property site_runtime_path¶

Returns:: 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.

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¶

Returns:: data directory tied to the user, e.g. /data/user/<userid>/<packagename>/files/<AppName>

property site_data_dir¶

Returns:: data directory shared by users, same as user_data_dir

property user_config_dir¶

Returns:: config directory tied to the user, e.g. /data/user/<userid>/<packagename>/shared_prefs/<AppName>

property site_config_dir¶

Returns:: config directory shared by users, same as user_config_dir

property user_cache_dir¶

Returns:: cache directory tied to the user, e.g.,``/data/user/<userid>/<packagename>/cache/<AppName>``

property site_cache_dir¶

Returns:: cache directory shared by users, same as user_cache_dir

property user_state_dir¶

Returns:: state directory tied to the user, same as user_data_dir

property site_state_dir¶

Returns:: state directory shared by users, same as user_state_dir

property user_log_dir¶

Returns:: 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¶

Returns:: log directory shared by users, same as user_log_dir

property user_documents_dir¶

Returns:: documents directory tied to the user e.g. /storage/emulated/0/Documents

property user_downloads_dir¶

Returns:: downloads directory tied to the user e.g. /storage/emulated/0/Downloads

property user_pictures_dir¶

Returns:: pictures directory tied to the user e.g. /storage/emulated/0/Pictures

property user_videos_dir¶

Returns:: videos directory tied to the user e.g. /storage/emulated/0/DCIM/Camera

property user_music_dir¶

Returns:: music directory tied to the user e.g. /storage/emulated/0/Music

property user_desktop_dir¶

Returns:: desktop directory tied to the user e.g. /storage/emulated/0/Desktop

property user_projects_dir¶

Returns:: projects directory tied to the user e.g. /storage/emulated/0/Projects

property user_publicshare_dir¶

Returns:: public share directory tied to the user e.g. /storage/emulated/0/Public

property user_templates_dir¶

Returns:: templates directory tied to the user e.g. /storage/emulated/0/Templates

property user_fonts_dir¶

Returns:: fonts directory tied to the user e.g. /storage/emulated/0/fonts

property user_preference_dir¶

Returns:: preference directory tied to the user, same as user_config_dir

property user_bin_dir¶

Returns:: bin directory tied to the user, e.g. /data/user/<userid>/<packagename>/files/bin

property site_bin_dir¶

Returns:: bin directory shared by users, same as user_bin_dir

property user_applications_dir¶

Returns:: applications directory tied to the user, same as user_data_dir

property site_applications_dir¶

Returns:: applications directory shared by users, same as user_applications_dir

property user_runtime_dir¶

Returns:: 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¶

Returns:: 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¶

Returns:: data directory tied to the user, or site equivalent when root with use_site_for_root

property user_config_dir¶

Returns:: config directory tied to the user, or site equivalent when root with use_site_for_root

property user_cache_dir¶

Returns:: cache directory tied to the user, or site equivalent when root with use_site_for_root

property user_state_dir¶

Returns:: state directory tied to the user, or site equivalent when root with use_site_for_root

property user_log_dir¶

Returns:: log directory tied to the user, or site equivalent when root with use_site_for_root

property user_applications_dir¶

Returns:: applications directory tied to the user, or site equivalent when root with use_site_for_root

property user_runtime_dir¶

Returns:: runtime directory tied to the user, or site equivalent when root with use_site_for_root

property user_bin_dir¶

Returns:: bin directory tied to the user, or site equivalent when root with use_site_for_root

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¶

Returns:: 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¶

Returns:: data directory shared by users, e.g. C:\ProgramData\$appauthor\$appname

property user_config_dir¶

Returns:: config directory tied to the user, same as user_data_dir

property site_config_dir¶

Returns:: config directory shared by users, same as site_data_dir

property user_cache_dir¶

Returns:: 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¶

Returns:: cache directory shared by users, e.g. C:\ProgramData\$appauthor\$appname\Cache\$version

property user_state_dir¶

Returns:: state directory tied to the user, same as user_data_dir

property site_state_dir¶

Returns:: state directory shared by users, same as site_data_dir

property user_log_dir¶

Returns:: log directory tied to the user, same as user_data_dir if not opinionated else Logs in it

property site_log_dir¶

Returns:: log directory shared by users, same as site_data_dir if not opinionated else Logs in it

property user_documents_dir¶

Returns:: documents directory tied to the user e.g. %USERPROFILE%\Documents

property user_downloads_dir¶

Returns:: downloads directory tied to the user e.g. %USERPROFILE%\Downloads

property user_pictures_dir¶

Returns:: pictures directory tied to the user e.g. %USERPROFILE%\Pictures

property user_videos_dir¶

Returns:: videos directory tied to the user e.g. %USERPROFILE%\Videos

property user_music_dir¶

Returns:: music directory tied to the user e.g. %USERPROFILE%\Music

property user_desktop_dir¶

Returns:: desktop directory tied to the user, e.g. %USERPROFILE%\Desktop

property user_projects_dir¶

Returns:: projects directory tied to the user, e.g. %USERPROFILE%\Projects

property user_publicshare_dir¶

Returns:: public share directory e.g. C:\Users\Public

property user_templates_dir¶

Returns:: templates directory tied to the user e.g. %APPDATA%\Microsoft\Windows\Templates

property user_fonts_dir¶

Returns:: fonts directory tied to the user e.g. %LOCALAPPDATA%\Microsoft\Windows\Fonts

property user_preference_dir¶

Returns:: preference directory tied to the user, same as user_config_dir

property user_bin_dir¶

Returns:: bin directory tied to the user, e.g. %LOCALAPPDATA%\Programs

property site_bin_dir¶

Returns:: bin directory shared by users, e.g. C:\ProgramDatain

property user_applications_dir¶

Returns:: applications directory tied to the user, e.g. Start Menu\Programs

property site_applications_dir¶

Returns:: applications directory shared by users, e.g. C:\ProgramData\Microsoft\Windows\Start Menu\Programs

property user_runtime_dir¶

Returns:: runtime directory tied to the user, e.g. %USERPROFILE%\AppData\Local\Temp\$appauthor\$appname

property site_runtime_dir¶

Returns:: 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¶

Backwards compatibility¶

Platforms¶

ABC¶

PlatformDirs¶

Android¶

macOS¶

Unix (Linux)¶

Windows¶