Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

the problem

https://github.com/platformdirs/platformdirs/workflows/Test/badge.svg

What directory should your app use for storing user data? If running on macOS, you should use:

~/Library/Application Support/<AppName>

If on Windows (at least English Win XP) that should be:

C:\Documents and Settings\<User>\Application Data\Local Settings\<AppAuthor>\<AppName>

or possibly:

C:\Documents and Settings\<User>\Application Data\<AppAuthor>\<AppName>

for roaming profiles but that is another story.

On Linux (and other Unices) the dir, according to the XDG spec, is:

~/.local/share/<AppName>

platformdirs to the rescue

This kind of thing is what the platformdirs module is for. platformdirs will help you choose an appropriate:

  • user data dir (user_data_dir)

  • user config dir (user_config_dir)

  • user cache dir (user_cache_dir)

  • site data dir (site_data_dir)

  • site config dir (site_config_dir)

  • user log dir (user_log_dir)

and also:

  • is a single module so other Python packages can include their own private copy

  • is slightly opinionated on the directory names used. Look for “OPINION” in documentation and code for when an opinion is being applied.

some example output

On macOS:

>>> from platformdirs import *
>>> appname = "SuperApp"
>>> appauthor = "Acme"
>>> user_data_dir(appname, appauthor)
'/Users/trentm/Library/Application Support/SuperApp'
>>> site_data_dir(appname, appauthor)
'/Library/Application Support/SuperApp'
>>> user_cache_dir(appname, appauthor)
'/Users/trentm/Library/Caches/SuperApp'
>>> user_log_dir(appname, appauthor)
'/Users/trentm/Library/Logs/SuperApp'

On Windows 7:

>>> from platformdirs import *
>>> appname = "SuperApp"
>>> appauthor = "Acme"
>>> user_data_dir(appname, appauthor)
'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp'
>>> user_data_dir(appname, appauthor, roaming=True)
'C:\\Users\\trentm\\AppData\\Roaming\\Acme\\SuperApp'
>>> user_cache_dir(appname, appauthor)
'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Cache'
>>> user_log_dir(appname, appauthor)
'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Logs'

On Linux:

>>> from platformdirs import *
>>> appname = "SuperApp"
>>> appauthor = "Acme"
>>> user_data_dir(appname, appauthor)
'/home/trentm/.local/share/SuperApp
>>> site_data_dir(appname, appauthor)
'/usr/local/share/SuperApp'
>>> site_data_dir(appname, appauthor, multipath=True)
'/usr/local/share/SuperApp:/usr/share/SuperApp'
>>> user_cache_dir(appname, appauthor)
'/home/trentm/.cache/SuperApp'
>>> user_log_dir(appname, appauthor)
'/home/trentm/.cache/SuperApp/log'
>>> user_config_dir(appname)
'/home/trentm/.config/SuperApp'
>>> site_config_dir(appname)
'/etc/xdg/SuperApp'
>>> os.environ['XDG_CONFIG_DIRS'] = '/etc:/usr/local/etc'
>>> site_config_dir(appname, multipath=True)
'/etc/SuperApp:/usr/local/etc/SuperApp'

PlatformDirs for convenience

>>> from platformdirs import PlatformDirs
>>> dirs = PlatformDirs("SuperApp", "Acme")
>>> dirs.user_data_dir
'/Users/trentm/Library/Application Support/SuperApp'
>>> dirs.site_data_dir
'/Library/Application Support/SuperApp'
>>> dirs.user_cache_dir
'/Users/trentm/Library/Caches/SuperApp'
>>> dirs.user_log_dir
'/Users/trentm/Library/Logs/SuperApp'

Per-version isolation

If you have multiple versions of your app in use that you want to be able to run side-by-side, then you may want version-isolation for these dirs:

>>> from platformdirs import PlatformDirs
>>> dirs = PlatformDirs("SuperApp", "Acme", version="1.0")
>>> dirs.user_data_dir
'/Users/trentm/Library/Application Support/SuperApp/1.0'
>>> dirs.site_data_dir
'/Library/Application Support/SuperApp/1.0'
>>> dirs.user_cache_dir
'/Users/trentm/Library/Caches/SuperApp/1.0'
>>> dirs.user_log_dir
'/Users/trentm/Library/Logs/SuperApp/1.0'

Contributing and About

This repository is a friendly fork of the wonderful work started by ActiveState who created appdirs, this package’s ancestor.

Contributions are most welcome.

platformdirs Changelog

platformdirs 2.0.0 (UNRELEASED)

  • Name change as part of the friendly fork

  • Add Python 3.7 support

  • Remove support for end-of-life Pythons 2.6, 3.2, and 3.3

appdirs 1.4.4

  • [PR #92] Don’t import appdirs from setup.py which resolves issue #91

  • [PR #100] Corrects the config directory on OSX/macOS, which resolves issue #63.

Project officially classified as Stable which is important for inclusion in other distros such as ActivePython.

appdirs 1.4.3

  • [PR #76] Python 3.6 invalid escape sequence deprecation fixes

  • Fix for Python 3.6 support

appdirs 1.4.2

  • [PR #84] Allow installing without setuptools

  • [PR #86] Fix string delimiters in setup.py description

  • Add Python 3.6 support

appdirs 1.4.1

  • [issue #38] Fix _winreg import on Windows Py3

  • [issue #55] Make appname optional

appdirs 1.4.0

  • [PR #42] AppAuthor is now optional on Windows

  • [issue 41] Support Jython on Windows, Mac, and Unix-like platforms. Windows support requires JNA.

  • [PR #44] Fix incorrect behaviour of the site_config_dir method

appdirs 1.3.0

  • [Unix, issue 16] Conform to XDG standard, instead of breaking it for everybody

  • [Unix] Removes gratuitous case mangling of the case, since *nix-es are usually case sensitive, so mangling is not wise

  • [Unix] Fixes the utterly wrong behaviour in site_data_dir, return result based on XDG_DATA_DIRS and make room for respecting the standard which specifies XDG_DATA_DIRS is a multiple-value variable

  • [Issue 6] Add *_config_dir which are distinct on nix-es, according to XDG specs; on Windows and Mac return the corresponding *_data_dir

appdirs 1.2.0

  • [Unix] Put user_log_dir under the cache dir on Unix. Seems to be more typical.

  • [issue 9] Make unicode work on py3k.

appdirs 1.1.0

  • [issue 4] Add AppDirs.user_log_dir.

  • [Unix, issue 2, issue 7] appdirs now conforms to XDG base directory spec.

  • [Mac, issue 5] Fix site_data_dir() on Mac.

  • [Mac] Drop use of ‘Carbon’ module in favour of hardcoded paths; supports Python3 now.

  • [Windows] Append “Cache” to user_cache_dir on Windows by default. Use opinion=False option to disable this.

  • Add appdirs.AppDirs convenience class. Usage:

    >>> dirs = AppDirs("SuperApp", "Acme", version="1.0")
    >>> dirs.user_data_dir
    '/Users/trentm/Library/Application Support/SuperApp/1.0'
    
  • [Windows] Cherry-pick Komodo’s change to downgrade paths to the Windows short paths if there are high bit chars.

  • [Linux] Change default user_cache_dir() on Linux to be singular, e.g. “~/.superapp/cache”.

  • [Windows] Add roaming option to user_data_dir() (for use on Windows only) and change the default user_data_dir behaviour to use a non-roaming profile dir (CSIDL_LOCAL_APPDATA instead of CSIDL_APPDATA). Why? Because a large roaming profile can cause login speed issues. The “only syncs on logout” behaviour can cause surprises in appdata info.

appdirs 1.0.1 (never released)

Started this changelog 27 July 2010. Before that this module originated in the Komodo product as applib.py and then as applib/location.py (used by PyPM in ActivePython). This is basically a fork of applib.py 1.0.1 and applib/location.py 1.0.1.

Metadata

Release files for platformdirs 2.0.0a3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for platformdirs 2.0.0a3
File Size Uploaded Provenance Actions
platformdirs-2.0.0a3.tar.gz 12.0 kB Without provenance Details for platformdirs-2.0.0a3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for platformdirs 2.0.0a3
File Interpreter ABI Platform Actions
platformdirs-2.0.0a3-py2.py3-none-any.whl Python 2, Python 3 none any Details for platformdirs-2.0.0a3-py2.py3-none-any.whl

Total release size: 22.1 kB

Release files / platformdirs-2.0.0a3.tar.gz

Download URL platformdirs-2.0.0a3.tar.gz
Size 12.0 kB
Tags Source
SHA-256 checksum
How to use checksums
d982848684555a2ffc9f51d6c28b94062624f5e2600328e326e937fc75f7a14c
BLAKE2b-256 checksum
How to use checksums
b76853f1b08abdacd9ba4478090970b2b6fbfdfc82933801c26f23c4f53aa035
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.9.5

Release files / platformdirs-2.0.0a3-py2.py3-none-any.whl

Download URL platformdirs-2.0.0a3-py2.py3-none-any.whl
Size 10.2 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
a26d4732214a64552e78752187732ddeda8c76ab0ab1dbf30935d967961cb028
BLAKE2b-256 checksum
How to use checksums
2c48bd2bb37da0518e190c892f1e3a8cae3ed6c366511f576e37708bab6e6a6d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.9.5

Security for platformdirs 2.0.0a3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page