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, ensure_exists=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, ensure_exists=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, ensure_exists=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, ensure_exists=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, ensure_exists=False)[source]
Parameters:
Return type:

str

Returns:

cache directory tied to the user

platformdirs.user_cache_path(appname=None, appauthor=None, version=None, opinion=True, ensure_exists=False)[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, ensure_exists=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, ensure_exists=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, ensure_exists=False)[source]
Parameters:
Return type:

str

Returns:

log directory tied to the user

platformdirs.user_log_path(appname=None, appauthor=None, version=None, opinion=True, ensure_exists=False)[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 a path tied to the user

User downloads directory

platformdirs.user_downloads_dir()[source]
Return type:

str

Returns:

downloads directory tied to the user

platformdirs.user_downloads_path()[source]
Return type:

Path

Returns:

downloads path tied to the user

User pictures directory

platformdirs.user_pictures_dir()[source]
Return type:

str

Returns:

pictures directory tied to the user

platformdirs.user_pictures_path()[source]
Return type:

Path

Returns:

pictures path tied to the user

User videos directory

platformdirs.user_videos_dir()[source]
Return type:

str

Returns:

videos directory tied to the user

platformdirs.user_videos_path()[source]
Return type:

Path

Returns:

videos path tied to the user

User music directory

platformdirs.user_music_dir()[source]
Return type:

str

Returns:

music directory tied to the user

platformdirs.user_music_path()[source]
Return type:

Path

Returns:

music path tied to the user

Runtime directory

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

str

Returns:

runtime directory tied to the user

platformdirs.user_runtime_path(appname=None, appauthor=None, version=None, opinion=True, ensure_exists=False)[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, ensure_exists=False)[source]
Parameters:
Return type:

str

Returns:

data directory shared by users

platformdirs.site_data_path(appname=None, appauthor=None, version=None, multipath=False, ensure_exists=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, ensure_exists=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, ensure_exists=False)[source]
Parameters:
Return type:

Path

Returns:

config path shared by the users

Shared cache directory

platformdirs.site_cache_dir(appname=None, appauthor=None, version=None, opinion=True, ensure_exists=False)[source]
Parameters:
Return type:

str

Returns:

cache directory tied to the user

platformdirs.site_cache_path(appname=None, appauthor=None, version=None, opinion=True, ensure_exists=False)[source]
Parameters:
Return type:

Path

Returns:

cache directory tied to the user

Platforms

ABC

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

Bases: ABC

Abstract base class for platform directories.

__init__(appname=None, appauthor=None, version=None, roaming=False, multipath=False, opinion=True, ensure_exists=False)[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 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.

ensure_exists

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

By default, no directories are created.

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

cache directory shared by users

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_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_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 the 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 user_log_path
Returns:

log path tied to the user

property user_documents_path
Returns:

documents a 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_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.

Return type:

Iterator[str]

iter_data_dirs()[source]
Yield:

all user and site data directories.

Return type:

Iterator[str]

iter_cache_dirs()[source]
Yield:

all user and site cache directories.

Return type:

Iterator[str]

iter_runtime_dirs()[source]
Yield:

all user and site runtime directories.

Return type:

Iterator[str]

iter_config_paths()[source]
Yield:

all user and site configuration paths.

Return type:

Iterator[Path]

iter_data_paths()[source]
Yield:

all user and site data paths.

Return type:

Iterator[Path]

iter_cache_paths()[source]
Yield:

all user and site cache paths.

Return type:

Iterator[Path]

iter_runtime_paths()[source]
Yield:

all user and site runtime paths.

Return type:

Iterator[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)[source]

Bases: PlatformDirsABC

Follows the guidance from here.

Makes use of the appname, version, 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 the 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 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_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_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)[source]

Bases: PlatformDirsABC

Platform directories for the macOS operating system.

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

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. If we’re using a Python binary managed by Homebrew, the directory will be under the Homebrew prefix, e.g. /opt/homebrew/share/$appname/$version. If multipath is enabled, and we’re in Homebrew, the response is a multi-path string separated by “:”, e.g. /opt/homebrew/share/$appname/$version:/Library/Application Support/$appname/$version

property site_data_path
Returns:

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

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

cache directory shared by users, e.g. /Library/Caches/$appname/$version. If we’re using a Python binary managed by Homebrew, the directory will be under the Homebrew prefix, e.g. /opt/homebrew/var/cache/$appname/$version. If multipath is enabled, and we’re in Homebrew, the response is a multi-path string separated by “:”, e.g. /opt/homebrew/var/cache/$appname/$version:/Library/Caches/$appname/$version

property site_cache_path
Returns:

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

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

downloads directory tied to the user, e.g. ~/Downloads

property user_pictures_dir
Returns:

pictures directory tied to the user, e.g. ~/Pictures

property user_videos_dir
Returns:

videos directory tied to the user, e.g. ~/Movies

property user_music_dir
Returns:

music directory tied to the user, e.g. ~/Music

property user_desktop_dir
Returns:

desktop directory tied to the user, e.g. ~/Desktop

property user_runtime_dir
Returns:

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

property site_runtime_dir
Returns:

runtime directory shared by users, same as user_runtime_dir

Unix (Linux)

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

Bases: PlatformDirsABC

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, 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_DIRS 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_CONFIG_DIRS 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 site_cache_dir
Returns:

cache directory shared by users, e.g. /var/cache/$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_downloads_dir
Returns:

downloads directory tied to the user, e.g. ~/Downloads

property user_pictures_dir
Returns:

pictures directory tied to the user, e.g. ~/Pictures

property user_videos_dir
Returns:

videos directory tied to the user, e.g. ~/Videos

property user_music_dir
Returns:

music directory tied to the user, e.g. ~/Music

property user_desktop_dir
Returns:

desktop directory tied to the user, e.g. ~/Desktop

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.

For FreeBSD/OpenBSD/NetBSD, it would return /var/run/user/$(id -u)/$appname/$version if exists, otherwise /tmp/runtime-$(id -u)/$appname/$version, if``$XDG_RUNTIME_DIR`` is not set.

property site_runtime_dir
Returns:

runtime directory shared by users, e.g. /run/$appname/$version or $XDG_RUNTIME_DIR/$appname/$version.

Note that this behaves almost exactly like user_runtime_dir if $XDG_RUNTIME_DIR is set, but will fall back to paths associated to the root user instead of a regular logged-in user if it’s not set.

If you wish to ensure that a logged-in root user path is returned e.g. /run/user/0, use user_runtime_dir instead.

For FreeBSD/OpenBSD/NetBSD, it would return /var/run/$appname/$version if $XDG_RUNTIME_DIR is not set.

property site_data_path
Returns:

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

property site_config_path
Returns:

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

property site_cache_path
Returns:

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

iter_config_dirs()[source]
Yield:

all user and site configuration directories.

Return type:

Iterator[str]

iter_data_dirs()[source]
Yield:

all user and site data directories.

Return type:

Iterator[str]

Windows

class platformdirs.windows.Windows(appname=None, appauthor=None, version=None, roaming=False, multipath=False, opinion=True, ensure_exists=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 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 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 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_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_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