Base Directories

The XDG Base Directory specification provides standard locations to store application data, configuration, and cached data.

Data directories

xdg.BaseDirectory.save_data_path(*resource)

Ensure $XDG_DATA_HOME/<resource>/ exists, and return its path. ‘resource’ should normally be the name of your application or a shared resource. Use this when saving or updating application data.

xdg.BaseDirectory.load_data_paths(*resource)

Returns an iterator which gives each directory named ‘resource’ in the application data search path. Information provided by earlier directories should take precedence over later ones.

xdg.BaseDirectory.xdg_data_home

$XDG_DATA_HOME or the default, ~/.local/share

xdg.BaseDirectory.xdg_data_dirs

A list of directory paths in which application data may be stored, in preference order.

Configuration directories

xdg.BaseDirectory.save_config_path(*resource)

Ensure $XDG_CONFIG_HOME/<resource>/ exists, and return its path. ‘resource’ should normally be the name of your application. Use this when saving configuration settings.

xdg.BaseDirectory.load_config_paths(*resource)

Returns an iterator which gives each directory named ‘resource’ in the configuration search path. Information provided by earlier directories should take precedence over later ones, and the user-specific config dir comes first.

xdg.BaseDirectory.load_first_config(*resource)

Returns the first result from load_config_paths, or None if there is nothing to load.

xdg.BaseDirectory.xdg_config_home

$XDG_CONFIG_HOME or the default, ~/.config

xdg.BaseDirectory.xdg_config_dirs

A list of directory paths in which configuration may be stored, in preference order.

Cache directory

xdg.BaseDirectory.save_cache_path(*resource)

Ensure $XDG_CACHE_HOME/<resource>/ exists, and return its path. ‘resource’ should normally be the name of your application or a shared resource.

xdg.BaseDirectory.xdg_cache_home

$XDG_CACHE_HOME or the default, ~/.cache

State directory

xdg.BaseDirectory.save_state_path(*resource)

Ensure $XDG_STATE_HOME/<resource>/ exists, and return its path. ‘resource’ should normally be the name of your application or a shared resource.

xdg.BaseDirectory.xdg_state_home

$XDG_STATE_HOME or the default, ~/.local/state

Runtime directory

xdg.BaseDirectory.get_runtime_dir(strict=True)

Returns the value of $XDG_RUNTIME_DIR, a directory path.

This directory is intended for ‘user-specific non-essential runtime files and other file objects (such as sockets, named pipes, …)’, and ‘communication and synchronization purposes’.

As of late 2012, only quite new systems set $XDG_RUNTIME_DIR. If it is not set, with strict=True (the default), a KeyError is raised. With strict=False, PyXDG will create a fallback under /tmp for the current user. This fallback does not provide the same guarantees as the specification requires for the runtime directory.

The strict default is deliberately conservative, so that application developers can make a conscious decision to allow the fallback.

New in version 0.25.