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

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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()[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

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

Parameters

appname (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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)[source]¶

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 (Optional[str]) – See appname.
appauthor (Union[str, None, ForwardRef]) – 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: str¶

Return type: str
Returns: data directory tied to the user

abstract property site_data_dir: str¶

Return type: str
Returns: data directory shared by users

abstract property user_config_dir: str¶

Return type: str
Returns: config directory tied to the user

abstract property site_config_dir: str¶

Return type: str
Returns: config directory shared by the users

abstract property user_cache_dir: str¶

Return type: str
Returns: cache directory tied to the user

abstract property user_state_dir: str¶

Return type: str
Returns: state directory tied to the user

abstract property user_log_dir: str¶

Return type: str
Returns: log directory tied to the user

abstract property user_documents_dir: str¶

Return type: str
Returns: documents directory tied to the user

abstract property user_runtime_dir: str¶

Return type: str
Returns: runtime directory tied to the user

property user_data_path: pathlib.Path¶

Return type: Path
Returns: data path tied to the user

property site_data_path: pathlib.Path¶

Return type: Path
Returns: data path shared by users

property user_config_path: pathlib.Path¶

Return type: Path
Returns: config path tied to the user

property site_config_path: pathlib.Path¶

Return type: Path
Returns: config path shared by the users

property user_cache_path: pathlib.Path¶

Return type: Path
Returns: cache path tied to the user

property user_state_path: pathlib.Path¶

Return type: Path
Returns: state path tied to the user

property user_log_path: pathlib.Path¶

Return type: Path
Returns: log path tied to the user

property user_documents_path: pathlib.Path¶

Return type: Path
Returns: documents path tied to the user

property user_runtime_path: pathlib.Path¶

Return type: 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: platformdirs.api.PlatformDirsABC

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

property user_data_dir: str¶

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

property site_data_dir: str¶

Return type: str
Returns: data directory shared by users, same as user_data_dir

property user_config_dir: str¶

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

property site_config_dir: str¶

Return type: str
Returns: config directory shared by the users, same as user_config_dir

property user_cache_dir: str¶

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

property user_state_dir: str¶

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

property user_log_dir: str¶

Return type: str
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: str¶

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

property user_runtime_dir: str¶

Return type: str
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: platformdirs.api.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: str¶

Return type: str
Returns: data directory tied to the user, e.g. ~/Library/Application Support/$appname/$version

property site_data_dir: str¶

Return type: str
Returns: data directory shared by users, e.g. /Library/Application Support/$appname/$version

property user_config_dir: str¶

Return type: str
Returns: config directory tied to the user, e.g. ~/Library/Preferences/$appname/$version

property site_config_dir: str¶

Return type: str
Returns: config directory shared by the users, e.g. /Library/Preferences/$appname

property user_cache_dir: str¶

Return type: str
Returns: cache directory tied to the user, e.g. ~/Library/Caches/$appname/$version

property user_state_dir: str¶

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

property user_log_dir: str¶

Return type: str
Returns: log directory tied to the user, e.g. ~/Library/Logs/$appname/$version

property user_documents_dir: str¶

Return type: str
Returns: documents directory tied to the user, e.g. ~/Documents

property user_runtime_dir: str¶

Return type: str
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: platformdirs.api.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: str¶

Return type: str
Returns: data directory tied to the user, e.g. ~/.local/share/$appname/$version or $XDG_DATA_HOME/$appname/$version

property site_data_dir: str¶

Return type: str
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: str¶

Return type: str
Returns: config directory tied to the user, e.g. ~/.config/$appname/$version or $XDG_CONFIG_HOME/$appname/$version

property site_config_dir: str¶

Return type: str
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: str¶

Return type: str
Returns: cache directory tied to the user, e.g. ~/.cache/$appname/$version or ~/$XDG_CACHE_HOME/$appname/$version

property user_state_dir: str¶

Return type: str
Returns: state directory tied to the user, e.g. ~/.local/state/$appname/$version or $XDG_STATE_HOME/$appname/$version

property user_log_dir: str¶

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

property user_documents_dir: str¶

Return type: str
Returns: documents directory tied to the user, e.g. ~/Documents

property user_runtime_dir: str¶

Return type: str
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: pathlib.Path¶

Return type: Path
Returns: data path shared by users. Only return first item, even if multipath is set to True

property site_config_path: pathlib.Path¶

Return type: 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: platformdirs.api.PlatformDirsABC

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

property user_data_dir: str¶

Return type: str
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: str¶

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

property user_config_dir: str¶

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

property site_config_dir: str¶

Return type: str
Returns: config directory shared by the users, same as site_data_dir

property user_cache_dir: str¶

Return type: str
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: str¶

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

property user_log_dir: str¶

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

property user_documents_dir: str¶

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

property user_runtime_dir: str¶

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

API¶

User directories¶

User data directory¶

User config directory¶

Cache directory¶

State directory¶

Logs directory¶

User documents directory¶

Runtime directory¶

Shared directories¶

Shared data directory¶

Shared config directory¶

Platforms¶

ABC¶

Android¶

macOS¶

Unix (Linux)¶

Windows¶

platformdirs

Navigation

Related Topics