API

User directories

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

User data directory

See also: user_data_dir

platformdirs.user_data_dir(appname=None, appauthor=None, version=None, roaming=False, ensure_exists=False, use_site_for_root=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• roaming (bool) – See roaming.

• ensure_exists (bool) – See ensure_exists.

• use_site_for_root (bool) – See use_site_for_root.

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, use_site_for_root=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• roaming (bool) – See roaming.

• ensure_exists (bool) – See ensure_exists.

• use_site_for_root (bool) – See use_site_for_root.

Return type:

Path

Returns:

data path tied to the user

User config directory

See also: user_config_dir

platformdirs.user_config_dir(appname=None, appauthor=None, version=None, roaming=False, ensure_exists=False, use_site_for_root=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• roaming (bool) – See roaming.

• ensure_exists (bool) – See ensure_exists.

• use_site_for_root (bool) – See use_site_for_root.

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, use_site_for_root=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• roaming (bool) – See roaming.

• ensure_exists (bool) – See ensure_exists.

• use_site_for_root (bool) – See use_site_for_root.

Return type:

Path

Returns:

config path tied to the user

User cache directory

See also: user_cache_dir

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

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• opinion (bool) – See opinion.

• ensure_exists (bool) – See ensure_exists.

• use_site_for_root (bool) – See use_site_for_root.

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, use_site_for_root=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• opinion (bool) – See opinion.

• ensure_exists (bool) – See ensure_exists.

• use_site_for_root (bool) – See use_site_for_root.

Return type:

Path

Returns:

cache path tied to the user

User state directory

See also: user_state_dir

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

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• roaming (bool) – See roaming.

• ensure_exists (bool) – See ensure_exists.

• use_site_for_root (bool) – See use_site_for_root.

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, use_site_for_root=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• roaming (bool) – See roaming.

• ensure_exists (bool) – See ensure_exists.

• use_site_for_root (bool) – See use_site_for_root.

Return type:

Path

Returns:

state path tied to the user

User log directory

See also: user_log_dir

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

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• opinion (bool) – See opinion.

• ensure_exists (bool) – See ensure_exists.

• use_site_for_root (bool) – See use_site_for_root.

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, use_site_for_root=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• opinion (bool) – See opinion.

• ensure_exists (bool) – See ensure_exists.

• use_site_for_root (bool) – See use_site_for_root.

Return type:

Path

Returns:

log path tied to the user

User runtime directory

See also: user_runtime_dir

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

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• opinion (bool) – See opinion.

• ensure_exists (bool) – See ensure_exists.

• use_site_for_root (bool) – See use_site_for_root.

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, use_site_for_root=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• opinion (bool) – See opinion.

• ensure_exists (bool) – See ensure_exists.

• use_site_for_root (bool) – See use_site_for_root.

Return type:

Path

Returns:

runtime path tied to the user

User applications directory

See also: user_applications_dir

Where application launchers and shortcuts are registered — .desktop files on Linux, the per-user Applications folder on macOS, or Start Menu shortcuts on Windows. These entries make applications discoverable in menus and app launchers.

platformdirs.user_applications_dir()

Return type:

str

Returns:

applications directory tied to the user

platformdirs.user_applications_path()

Return type:

Path

Returns:

applications path tied to the user

User binary directory

See also: user_bin_dir

Where user-installed executables and scripts are placed so they appear on $PATH — ~/.local/bin on Linux/macOS or %LOCALAPPDATA%\Programs on Windows.

platformdirs.user_bin_dir()

Return type:

str

Returns:

bin directory tied to the user

platformdirs.user_bin_path()

Return type:

Path

Returns:

bin path tied to the user

User documents directory

See also: user_documents_dir

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

User downloads directory

See also: user_downloads_dir

platformdirs.user_downloads_dir()

Return type:

str

Returns:

downloads directory tied to the user

platformdirs.user_downloads_path()

Return type:

Path

Returns:

downloads path tied to the user

User pictures directory

See also: user_pictures_dir

platformdirs.user_pictures_dir()

Return type:

str

Returns:

pictures directory tied to the user

platformdirs.user_pictures_path()

Return type:

Path

Returns:

pictures path tied to the user

User videos directory

See also: user_videos_dir

platformdirs.user_videos_dir()

Return type:

str

Returns:

videos directory tied to the user

platformdirs.user_videos_path()

Return type:

Path

Returns:

videos path tied to the user

User music directory

See also: user_music_dir

platformdirs.user_music_dir()

Return type:

str

Returns:

music directory tied to the user

platformdirs.user_music_path()

Return type:

Path

Returns:

music path tied to the user

User desktop directory

See also: user_desktop_dir

platformdirs.user_desktop_dir()

Return type:

str

Returns:

desktop directory tied to the user

platformdirs.user_desktop_path()

Return type:

Path

Returns:

desktop path tied to the user

User projects directory

See also: user_projects_dir

platformdirs.user_projects_dir()

Return type:

str

Returns:

projects directory tied to the user

platformdirs.user_projects_path()

Return type:

Path

Returns:

projects path tied to the user

User public share directory

See also: user_publicshare_dir

platformdirs.user_publicshare_dir()

Return type:

str

Returns:

public share directory tied to the user

platformdirs.user_publicshare_path()

Return type:

Path

Returns:

public share path tied to the user

User templates directory

See also: user_templates_dir

platformdirs.user_templates_dir()

Return type:

str

Returns:

templates directory tied to the user

platformdirs.user_templates_path()

Return type:

Path

Returns:

templates path tied to the user

User fonts directory

See also: user_fonts_dir

platformdirs.user_fonts_dir()

Return type:

str

Returns:

fonts directory tied to the user

platformdirs.user_fonts_path()

Return type:

Path

Returns:

fonts path tied to the user

User preference directory

See also: user_preference_dir

platformdirs.user_preference_dir()

Return type:

str

Returns:

preference directory tied to the user

platformdirs.user_preference_path()

Return type:

Path

Returns:

preference path tied to the user

Shared directories

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

Shared data directory

See also: site_data_dir

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

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• multipath (bool) – See multipath.

• ensure_exists (bool) – See ensure_exists.

Return type:

str

Returns:

data directory shared by users

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

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• multipath (bool) – See multipath.

• ensure_exists (bool) – See ensure_exists.

Return type:

Path

Returns:

data path shared by users

Shared config directory

See also: site_config_dir

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

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• multipath (bool) – See multipath.

• ensure_exists (bool) – See ensure_exists.

Return type:

str

Returns:

config directory shared by users

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

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• multipath (bool) – See multipath.

• ensure_exists (bool) – See ensure_exists.

Return type:

Path

Returns:

config path shared by users

Shared cache directory

See also: site_cache_dir

platformdirs.site_cache_dir(appname=None, appauthor=None, version=None, opinion=True, ensure_exists=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• opinion (bool) – See opinion.

• ensure_exists (bool) – See ensure_exists.

Return type:

str

Returns:

cache directory shared by users

platformdirs.site_cache_path(appname=None, appauthor=None, version=None, opinion=True, ensure_exists=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• opinion (bool) – See opinion.

• ensure_exists (bool) – See ensure_exists.

Return type:

Path

Returns:

cache path shared by users

Shared state directory

See also: site_state_dir

platformdirs.site_state_dir(appname=None, appauthor=None, version=None, ensure_exists=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• ensure_exists (bool) – See ensure_exists.

Return type:

str

Returns:

state directory shared by users

platformdirs.site_state_path(appname=None, appauthor=None, version=None, ensure_exists=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• ensure_exists (bool) – See ensure_exists.

Return type:

Path

Returns:

state path shared by users

Shared log directory

See also: site_log_dir

platformdirs.site_log_dir(appname=None, appauthor=None, version=None, opinion=True, ensure_exists=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• opinion (bool) – See opinion.

• ensure_exists (bool) – See ensure_exists.

Return type:

str

Returns:

log directory shared by users

platformdirs.site_log_path(appname=None, appauthor=None, version=None, opinion=True, ensure_exists=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• opinion (bool) – See opinion.

• ensure_exists (bool) – See ensure_exists.

Return type:

Path

Returns:

log path shared by users

Shared runtime directory

See also: site_runtime_dir

platformdirs.site_runtime_dir(appname=None, appauthor=None, version=None, opinion=True, ensure_exists=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• opinion (bool) – See opinion.

• ensure_exists (bool) – See ensure_exists.

Return type:

str

Returns:

runtime directory shared by users

platformdirs.site_runtime_path(appname=None, appauthor=None, version=None, opinion=True, ensure_exists=False)

Parameters:

• appname (str | None) – See appname.

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

• version (str | None) – See version.

• opinion (bool) – See opinion.

• ensure_exists (bool) – See ensure_exists.

Return type:

Path

Returns:

runtime path shared by users

Shared applications directory

See also: site_applications_dir

Where application launchers and shortcuts are registered system-wide — .desktop files in /usr/share/applications on Linux, /Applications on macOS, or the All Users Start Menu on Windows. Applications installed here are available to all users.

platformdirs.site_applications_dir(multipath=False, ensure_exists=False)

Parameters:

• multipath (bool) – See multipath.

• ensure_exists (bool) – See ensure_exists.

Return type:

str

Returns:

applications directory shared by users

platformdirs.site_applications_path(multipath=False, ensure_exists=False)

Parameters:

• multipath (bool) – See multipath.

• ensure_exists (bool) – See ensure_exists.

Return type:

Path

Returns:

applications path shared by users

Shared binary directory

See also: site_bin_dir

Where system-wide executables and scripts are placed — /usr/local/bin on Linux/macOS or %ProgramData%\bin on Windows. Executables here are available to all users.

platformdirs.site_bin_dir()

Return type:

str

Returns:

bin directory shared by users

platformdirs.site_bin_path()

Return type:

Path

Returns:

bin path shared by users

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)

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)

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

Data directory tied to the user.

abstract property site_data_dir

Data directory shared by users.

abstract property user_config_dir

Config directory tied to the user.

abstract property site_config_dir

Config directory shared by users.

abstract property user_cache_dir

Cache directory tied to the user.

abstract property site_cache_dir

Cache directory shared by users.

abstract property user_state_dir

State directory tied to the user.

abstract property site_state_dir

State directory shared by users.

abstract property user_log_dir

Log directory tied to the user.

abstract property site_log_dir

Log directory shared by users.

abstract property user_documents_dir

Documents directory tied to the user.

abstract property user_downloads_dir

Downloads directory tied to the user.

abstract property user_pictures_dir

Pictures directory tied to the user.

abstract property user_videos_dir

Videos directory tied to the user.

abstract property user_music_dir

Music directory tied to the user.

abstract property user_desktop_dir

Desktop directory tied to the user.

abstract property user_projects_dir

Projects directory tied to the user.

abstract property user_publicshare_dir

Public share directory tied to the user.

abstract property user_templates_dir

Templates directory tied to the user.

abstract property user_fonts_dir

Fonts directory tied to the user.

abstract property user_preference_dir

Preference directory tied to the user.

abstract property user_bin_dir

Bin directory tied to the user.

abstract property site_bin_dir

Bin directory shared by users.

abstract property user_applications_dir

Applications directory tied to the user.

abstract property site_applications_dir

Applications directory shared by users.

abstract property user_runtime_dir

Runtime directory tied to the user.

abstract property site_runtime_dir

Runtime directory shared by users.

property user_data_path

Data path tied to the user.

property site_data_path

Data path shared by users.

property user_config_path

Config path tied to the user.

property site_config_path

Config path shared by users.

property user_cache_path

Cache path tied to the user.

property site_cache_path

Cache path shared by users.

property user_state_path

State path tied to the user.

property site_state_path

State path shared by users.

property user_log_path

Log path tied to the user.

property site_log_path

Log path shared by users.

property user_documents_path

Documents path tied to the user.

property user_downloads_path

Downloads path tied to the user.

property user_pictures_path

Pictures path tied to the user.

property user_videos_path

Videos path tied to the user.

property user_music_path

Music path tied to the user.

property user_desktop_path

Desktop path tied to the user.

property user_projects_path

Projects path tied to the user.

property user_publicshare_path

Public share path tied to the user.

property user_templates_path

Templates path tied to the user.

property user_fonts_path

Fonts path tied to the user.

property user_preference_path

Preference path tied to the user.

property user_bin_path

Bin path tied to the user.

property site_bin_path

Bin path shared by users.

property user_applications_path

Applications path tied to the user.

property site_applications_path

Applications path shared by users.

property user_runtime_path

Runtime path tied to the user.

property site_runtime_path

Runtime path shared by users.

iter_config_dirs()

Yield:

all user and site configuration directories.

iter_data_dirs()

Yield:

all user and site data directories.

iter_cache_dirs()

Yield:

all user and site cache directories.

iter_state_dirs()

Yield:

all user and site state directories.

iter_log_dirs()

Yield:

all user and site log directories.

iter_runtime_dirs()

Yield:

all user and site runtime directories.

iter_config_paths()

Yield:

all user and site configuration paths.

iter_data_paths()

Yield:

all user and site data paths.

iter_cache_paths()

Yield:

all user and site cache paths.

iter_state_paths()

Yield:

all user and site state paths.

iter_log_paths()

Yield:

all user and site log paths.

iter_runtime_paths()

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)

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

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

property site_data_dir

Data directory shared by users, same as user_data_dir.

property user_config_dir

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

property site_config_dir

Config directory shared by users, same as user_config_dir.

property user_cache_dir

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

property site_cache_dir

Cache directory shared by users, same as user_cache_dir.

property user_state_dir

State directory tied to the user, same as user_data_dir.

property site_state_dir

State directory shared by users, same as user_state_dir.

property user_log_dir

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

Log directory shared by users, same as user_log_dir.

property user_documents_dir

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

property user_downloads_dir

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

property user_pictures_dir

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

property user_videos_dir

Videos directory tied to the user e.g. /storage/emulated/0/DCIM/Camera.

property user_music_dir

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

property user_desktop_dir

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

property user_projects_dir

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

property user_publicshare_dir

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

property user_templates_dir

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

property user_fonts_dir

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

property user_preference_dir

Preference directory tied to the user, same as user_config_dir.

property user_bin_dir

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

property site_bin_dir

Bin directory shared by users, same as user_bin_dir.

property user_applications_dir

Applications directory tied to the user, same as user_data_dir.

property site_applications_dir

Applications directory shared by users, same as user_applications_dir.

property user_runtime_dir

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

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)

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)

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

Data directory tied to the user, or site equivalent when root with use_site_for_root.

property user_config_dir

Config directory tied to the user, or site equivalent when root with use_site_for_root.

property user_cache_dir

Cache directory tied to the user, or site equivalent when root with use_site_for_root.

property user_state_dir

State directory tied to the user, or site equivalent when root with use_site_for_root.

property user_log_dir

Log directory tied to the user, or site equivalent when root with use_site_for_root.

property user_applications_dir

Applications directory tied to the user, or site equivalent when root with use_site_for_root.

property user_runtime_dir

Runtime directory tied to the user, or site equivalent when root with use_site_for_root.

property user_bin_dir

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)

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

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

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

property user_config_dir

Config directory tied to the user, same as user_data_dir.

property site_config_dir

Config directory shared by users, same as site_data_dir.

property user_cache_dir

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

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

property user_state_dir

State directory tied to the user, same as user_data_dir.

property site_state_dir

State directory shared by users, same as site_data_dir.

property user_log_dir

Log directory tied to the user, same as user_data_dir if not opinionated else Logs in it.

property site_log_dir

Log directory shared by users, same as site_data_dir if not opinionated else Logs in it.

property user_documents_dir

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

property user_downloads_dir

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

property user_pictures_dir

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

property user_videos_dir

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

property user_music_dir

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

property user_desktop_dir

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

property user_projects_dir

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

property user_publicshare_dir

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

property user_templates_dir

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

property user_fonts_dir

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

property user_preference_dir

Preference directory tied to the user, same as user_config_dir.

property user_bin_dir

Bin directory tied to the user, e.g. %LOCALAPPDATA%\Programs.

property site_bin_dir

Bin directory shared by users, e.g. C:\ProgramData\bin.

property user_applications_dir

Applications directory tied to the user, e.g. Start Menu\Programs.

property site_applications_dir

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

property user_runtime_dir

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

property site_runtime_dir

Runtime directory shared by users, same as user_runtime_dir.