The problem

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

When writing desktop application, finding the right location to store user data and configuration varies per platform. Even for single-platform apps, there may by plenty of nuances in figuring out the right location.

For example, 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), according to the XDG Basedir Spec, it should be:

~/.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)

  • user documents dir (user_documents_dir)

  • user runtime dir (user_runtime_dir)

And also:

  • Is a single module so other Python packages can vendor 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.

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'
>>> user_documents_dir()
'/Users/trentm/Documents'
>>> user_runtime_dir(appname, appauthor)
'/Users/trentm/Library/Caches/TemporaryItems/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'
>>> user_documents_dir()
'C:\\Users\\trentm\\Documents'
>>> user_runtime_dir(appname, appauthor)
'C:\\Users\\trentm\\AppData\\Local\\Temp\\Acme\\SuperApp'

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'
>>> user_documents_dir()
'/home/trentm/Documents'
>>> user_runtime_dir(appname, appauthor)
'/run/user/{os.getuid()}/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'

On Android:

>>> from platformdirs import *
>>> appname = "SuperApp"
>>> appauthor = "Acme"
>>> user_data_dir(appname, appauthor)
'/data/data/com.termux/files/SuperApp'
>>> user_cache_dir(appname, appauthor)
'/data/data/com.termux/cache/SuperApp'
>>> user_log_dir(appname, appauthor)
'/data/data/com.termux/cache/SuperApp/log'
>>> user_config_dir(appname)
'/data/data/com.termux/shared_prefs/SuperApp'
>>> user_documents_dir()
'/storage/emulated/0/Documents'
>>> user_runtime_dir(appname, appauthor)
'/data/data/com.termux/cache/SuperApp/tmp'

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'
>>> dirs.user_documents_dir
'/Users/trentm/Documents'
>>> dirs.user_runtime_dir
'/Users/trentm/Library/Caches/TemporaryItems/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'
>>> dirs.user_documents_dir
'/Users/trentm/Documents'
>>> dirs.user_runtime_dir
'/Users/trentm/Library/Caches/TemporaryItems/SuperApp/1.0'

Be wary of using this for configuration files though; you’ll need to handle migrating configuration files manually.

Why this Fork?

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

Maintaining an open source project is no easy task, particularly from within an organization, and the Python community is indebted to appdirs (and to Trent Mick and Jeff Rouse in particular) for creating an incredibly useful simple module, as evidenced by the wide number of users it has attracted over the years.

Nonetheless, given the number of long-standing open issues and pull requests, and no clear path towards ensuring that maintenance of the package would continue or grow, this fork was created.

Contributions are most welcome.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (4.11.8)

Owner

PyPI data
Data sourced directly from PyPI's database.

3 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for Julian from gravatar.com Julian Avatar for Ofekmeister from gravatar.com Ofekmeister Avatar for ronny from gravatar.com ronny

Credits

Maintainer: Bernát Gábor, Julian Berman, Ofek Lev, Ronny Pfannschmidt

License

MIT License (MIT)

Requires

Python >=3.6

Tags

application directory log cache user

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

platformdirs-2.4.0.tar.gz (24.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

platformdirs-2.4.0-py3-none-any.whl (14.4 kB view details)

Uploaded Python 3

File details

Details for the file platformdirs-2.4.0.tar.gz.

File metadata

  • Download URL: platformdirs-2.4.0.tar.gz
  • Upload date:
  • Size: 24.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.7

File hashes

Hashes for platformdirs-2.4.0.tar.gz
Algorithm Hash digest
SHA256 367a5e80b3d04d2428ffa76d33f124cf11e8fff2acdaa9b43d545f5c7d661ef2
MD5 4e5b836d19600cc4bf0b789ab1de3b51
BLAKE2b-256 4b96d70b9462671fbeaacba4639ff866fb4e9e558580853fc5d6e698d0371ad4

See more details on using hashes here.

File details

Details for the file platformdirs-2.4.0-py3-none-any.whl.

File metadata

  • Download URL: platformdirs-2.4.0-py3-none-any.whl
  • Upload date:
  • Size: 14.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.7

File hashes

Hashes for platformdirs-2.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8868bbe3c3c80d42f20156f22e7131d2fb321f5bc86a2a345375c6481a67021d
MD5 8c8b02ee007d405bf3369b82b7a4c1ca
BLAKE2b-256 b178dcfd84d3aabd46a9c77260fb47ea5d244806e4daef83aa6fe5d83adb182c

See more details on using hashes here.

Release history Release notifications | RSS feed

4.11.8

2 files

4.11.7

2 files

4.11.6

2 files

4.11.5

2 files

4.11.4

2 files

4.11.3

2 files

4.11.2

2 files

4.11.1

2 files

4.11.0

2 files

4.10.1

2 files

4.10.0

2 files

4.9.6

2 files

4.9.4

2 files

4.9.2

2 files

4.9.1

2 files

4.9.0

2 files

4.8.0

2 files

4.7.1

2 files

4.7.0

2 files

4.6.0

2 files

4.5.1

2 files

4.5.0

2 files

4.4.0

2 files

4.3.8

2 files

4.3.7

2 files

4.3.6

2 files

4.3.5

2 files

4.3.4

2 files

4.3.3

2 files

4.3.2

2 files

4.3.1

2 files

4.3.0

2 files

4.2.2

2 files

4.2.1

2 files

4.2.0

2 files

4.1.0

2 files

4.0.0

2 files

3.11.0

2 files

3.10.0

2 files

3.9.1

2 files

3.9.0

2 files

3.8.1

2 files

3.8.0

2 files

3.7.0

2 files

3.6.0

2 files

3.5.3

2 files

3.5.2

2 files

3.5.1

2 files

3.5.0

2 files

3.4.0

2 files

3.3.0

2 files

3.2.0

2 files

3.1.1

2 files

3.1.0

2 files

3.0.0

2 files

2.6.2

2 files

2.6.1

2 files

2.6.0

2 files

2.5.4

2 files

2.5.3

2 files

2.5.2

2 files

2.5.1

2 files

2.5.0

2 files

2.4.1

2 files

This release

2.4.0 This release

2 files

2.3.0

2 files

2.2.0

2 files

2.1.0

2 files

2.0.2

2 files

2.0.0

2 files

Pre-release

2.0.0a3

2 files

Pre-release

2.0.0a2

2 files

Pre-release

2.0.0a1

2 files

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