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)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• roaming (bool) – See roaming.

Return type:

str

Returns:

data directory tied to the user

platformdirs.user_data_path(appname=None, appauthor=None, version=None, roaming=False)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• roaming (bool) – See roaming.

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)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• roaming (bool) – See roaming.

Return type:

str

Returns:

config directory tied to the user

platformdirs.user_config_path(appname=None, appauthor=None, version=None, roaming=False)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• roaming (bool) – See roaming.

Return type:

Path

Returns:

config path tied to the user

Cache directory

platformdirs.user_cache_dir(appname=None, appauthor=None, version=None, opinion=True)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• opinion (bool) – See roaming.

Return type:

str

Returns:

cache directory tied to the user

platformdirs.user_cache_path(appname=None, appauthor=None, version=None, opinion=True)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• opinion (bool) – See roaming.

Return type:

Path

Returns:

cache path tied to the user

State directory

platformdirs.user_state_dir(appname=None, appauthor=None, version=None, roaming=False)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• roaming (bool) – See roaming.

Return type:

str

Returns:

state directory tied to the user

platformdirs.user_state_path(appname=None, appauthor=None, version=None, roaming=False)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• roaming (bool) – See roaming.

Return type:

Path

Returns:

state path tied to the user

Logs directory

platformdirs.user_log_dir(appname=None, appauthor=None, version=None, opinion=True)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• opinion (bool) – See roaming.

Return type:

str

Returns:

log directory tied to the user

platformdirs.user_log_path(appname=None, appauthor=None, version=None, opinion=True)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• opinion (bool) – See roaming.

Return type:

Path

Returns:

log path tied to the user

User documents directory

platformdirs.user_documents_dir()

Return type:

str

Returns:

documents directory tied to the user

platformdirs.user_documents_path()

Return type:

Path

Returns:

documents path tied to the user

Runtime directory

platformdirs.user_runtime_dir(appname=None, appauthor=None, version=None, opinion=True)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• opinion (bool) – See opinion.

Return type:

str

Returns:

runtime directory tied to the user

platformdirs.user_runtime_path(appname=None, appauthor=None, version=None, opinion=True)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• opinion (bool) – See opinion.

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)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• multipath (bool) – See roaming.

Return type:

str

Returns:

data directory shared by users

platformdirs.site_data_path(appname=None, appauthor=None, version=None, multipath=False)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• multipath (bool) – See multipath.

Return type:

Path

Returns:

data path shared by users

Shared config directory

platformdirs.site_config_dir(appname=None, appauthor=None, version=None, multipath=False)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• multipath (bool) – See roaming.

Return type:

str

Returns:

config directory shared by the users

platformdirs.site_config_path(appname=None, appauthor=None, version=None, multipath=False)

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• multipath (bool) – See roaming.

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)

Bases: ABC

Abstract base class for platform directories.

__init__(appname=None, appauthor=None, version=None, roaming=False, multipath=False, opinion=True)

Create a new platform directory.

Parameters:

• appname (Optional[str]) – See appname.

• appauthor (Union[str, None, Literal[False]]) – See appauthor.

• version (Optional[str]) – See version.

• roaming (bool) – See roaming.

• multipath (bool) – See multipath.

• opinion (bool) – See opinion.

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)

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)

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)

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)

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