API#

User directories#

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

User data directory#

platformdirs.user_data_dir(appname=None, appauthor=None, version=None, roaming=False)[source]#
Parameters:
Return type:

str

Returns:

data directory tied to the user

platformdirs.user_data_path(appname=None, appauthor=None, version=None, roaming=False)[source]#
Parameters:
Return type:

Path

Returns:

data path tied to the user

User config directory#

platformdirs.user_config_dir(appname=None, appauthor=None, version=None, roaming=False)[source]#
Parameters:
Return type:

str

Returns:

config directory tied to the user

platformdirs.user_config_path(appname=None, appauthor=None, version=None, roaming=False)[source]#
Parameters:
Return type:

Path

Returns:

config path tied to the user

Cache directory#

platformdirs.user_cache_dir(appname=None, appauthor=None, version=None, opinion=True)[source]#
Parameters:
Return type:

str

Returns:

cache directory tied to the user

platformdirs.user_cache_path(appname=None, appauthor=None, version=None, opinion=True)[source]#
Parameters:
Return type:

Path

Returns:

cache path tied to the user

State directory#

platformdirs.user_state_dir(appname=None, appauthor=None, version=None, roaming=False)[source]#
Parameters:
Return type:

str

Returns:

state directory tied to the user

platformdirs.user_state_path(appname=None, appauthor=None, version=None, roaming=False)[source]#
Parameters:
Return type:

Path

Returns:

state path tied to the user

Logs directory#

platformdirs.user_log_dir(appname=None, appauthor=None, version=None, opinion=True)[source]#
Parameters:
Return type:

str

Returns:

log directory tied to the user

platformdirs.user_log_path(appname=None, appauthor=None, version=None, opinion=True)[source]#
Parameters:
Return type:

Path

Returns:

log path tied to the user

User documents directory#

platformdirs.user_documents_dir()[source]#
Return type:

str

Returns:

documents directory tied to the user

platformdirs.user_documents_path()[source]#
Return type:

Path

Returns:

documents path tied to the user

Runtime directory#

platformdirs.user_runtime_dir(appname=None, appauthor=None, version=None, opinion=True)[source]#
Parameters:
Return type:

str

Returns:

runtime directory tied to the user

platformdirs.user_runtime_path(appname=None, appauthor=None, version=None, opinion=True)[source]#
Parameters:
Return type:

Path

Returns:

runtime path tied to the user

Shared directories#

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

Shared data directory#

platformdirs.site_data_dir(appname=None, appauthor=None, version=None, multipath=False)[source]#
Parameters:
Return type:

str

Returns:

data directory shared by users

platformdirs.site_data_path(appname=None, appauthor=None, version=None, multipath=False)[source]#
Parameters:
Return type:

Path

Returns:

data path shared by users

Shared config directory#

platformdirs.site_config_dir(appname=None, appauthor=None, version=None, multipath=False)[source]#
Parameters:
Return type:

str

Returns:

config directory shared by the users

platformdirs.site_config_path(appname=None, appauthor=None, version=None, multipath=False)[source]#
Parameters:
Return type:

Path

Returns:

config path shared by the users

Platforms#

ABC#

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

Bases: ABC

Abstract base class for platform directories.

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

Create a new platform directory.

Parameters:
appname#

The name of 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.

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 only applicable to Unix/Linux which indicates that the entire list of data dirs should be returned. By default, the first item would only be returned.

opinion#

A flag to indicating to use opinionated values.

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 the users

abstract property user_cache_dir#
Returns:

cache directory tied to the user

abstract property user_state_dir#
Returns:

state directory tied to the user

abstract property user_log_dir#
Returns:

log directory tied to the user

abstract property user_documents_dir#
Returns:

documents directory tied to the user

abstract property user_runtime_dir#
Returns:

runtime directory tied to the user

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 the users

property user_cache_path#
Returns:

cache path tied to the user

property user_state_path#
Returns:

state path tied to the user

property user_log_path#
Returns:

log path tied to the user

property user_documents_path#
Returns:

documents path tied to the user

property user_runtime_path#
Returns:

runtime path tied to the user

Android#

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

Bases: PlatformDirsABC

Follows the guidance from here. Makes use of the appname and version.

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 the users, same as user_config_dir

property user_cache_dir#
Returns:

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

property user_state_dir#
Returns:

state directory tied to the user, same as user_data_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 user_documents_dir#
Returns:

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

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

macOS#

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

Bases: PlatformDirsABC

Platform directories for the macOS operating system. Follows the guidance from Apple documentation. Makes use of the appname and version.

property user_data_dir#
Returns:

data directory tied to the user, e.g. ~/Library/Application Support/$appname/$version

property site_data_dir#
Returns:

data directory shared by users, e.g. /Library/Application Support/$appname/$version

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 the users, same as site_data_dir

property user_cache_dir#
Returns:

cache directory tied to the user, e.g. ~/Library/Caches/$appname/$version

property user_state_dir#
Returns:

state directory tied to the user, same as user_data_dir

property user_log_dir#
Returns:

log directory tied to the user, e.g. ~/Library/Logs/$appname/$version

property user_documents_dir#
Returns:

documents directory tied to the user, e.g. ~/Documents

property user_runtime_dir#
Returns:

runtime directory tied to the user, e.g. ~/Library/Caches/TemporaryItems/$appname/$version

Unix (Linux)#

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

Bases: PlatformDirsABC

On Unix/Linux, we follow the XDG Basedir Spec. The spec allows overriding directories with environment variables. The examples show are the default values, alongside the name of the environment variable that overrides them. Makes use of the appname, version, multipath, opinion.

property user_data_dir#
Returns:

data directory tied to the user, e.g. ~/.local/share/$appname/$version or $XDG_DATA_HOME/$appname/$version

property site_data_dir#
Returns:

data directories shared by users (if multipath is enabled and XDG_DATA_DIR is set and a multi path the response is also a multi path separated by the OS path separator), e.g. /usr/local/share/$appname/$version or /usr/share/$appname/$version

property user_config_dir#
Returns:

config directory tied to the user, e.g. ~/.config/$appname/$version or $XDG_CONFIG_HOME/$appname/$version

property site_config_dir#
Returns:

config directories shared by users (if multipath is enabled and XDG_DATA_DIR is set and a multi path the response is also a multi path separated by the OS path separator), e.g. /etc/xdg/$appname/$version

property user_cache_dir#
Returns:

cache directory tied to the user, e.g. ~/.cache/$appname/$version or ~/$XDG_CACHE_HOME/$appname/$version

property user_state_dir#
Returns:

state directory tied to the user, e.g. ~/.local/state/$appname/$version or $XDG_STATE_HOME/$appname/$version

property user_log_dir#
Returns:

log directory tied to the user, same as user_state_dir if not opinionated else log in it

property user_documents_dir#
Returns:

documents directory tied to the user, e.g. ~/Documents

property user_runtime_dir#
Returns:

runtime directory tied to the user, e.g. /run/user/$(id -u)/$appname/$version or $XDG_RUNTIME_DIR/$appname/$version

property site_data_path#
Returns:

data path shared by users. Only return first item, even if multipath is set to True

property site_config_path#
Returns:

config path shared by the users. Only return first item, even if multipath is set to True

Windows#

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

Bases: PlatformDirsABC

MSDN on where to store app data files. Makes use of the appname, appauthor, version, roaming, opinion.

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 the 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 user_state_dir#
Returns:

state directory tied to the user, same as user_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 user_documents_dir#
Returns:

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

property user_runtime_dir#
Returns:

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