Repository files navigation

When writing desktop application, finding the right location to store user dataand configuration varies per platform. Even for single-platform apps, theremay 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) 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>

forroaming profiles but that is another story.

On Linux (and other Unices), according to theXDG Basedir Spec, it should be:

~/.local/share/<AppName>

This kind of thing is what theplatformdirs package 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 downloads dir (user_downloads_dir)
• user pictures dir (user_pictures_dir)
• user videos dir (user_videos_dir)
• user music dir (user_music_dir)
• user desktop dir (user_desktop_dir)
• user runtime dir (user_runtime_dir)

And also:

• Is slightly opinionated on the directory names used. Look for "OPINION" indocumentation and code for when an opinion is being applied.

On macOS:

>>>from platformdirsimport*>>> 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_downloads_dir()'/Users/trentm/Downloads'>>> user_pictures_dir()'/Users/trentm/Pictures'>>> user_videos_dir()'/Users/trentm/Movies'>>> user_music_dir()'/Users/trentm/Music'>>> user_desktop_dir()'/Users/trentm/Desktop'>>> user_runtime_dir(appname, appauthor)'/Users/trentm/Library/Caches/TemporaryItems/SuperApp'

On Windows:

>>>from platformdirsimport*>>> 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_downloads_dir()'C:\\Users\\trentm\\Downloads'>>> user_pictures_dir()'C:\\Users\\trentm\\Pictures'>>> user_videos_dir()'C:\\Users\\trentm\\Videos'>>> user_music_dir()'C:\\Users\\trentm\\Music'>>> user_desktop_dir()'C:\\Users\\trentm\\Desktop'>>> user_runtime_dir(appname, appauthor)'C:\\Users\\trentm\\AppData\\Local\\Temp\\Acme\\SuperApp'

On Linux:

>>>from platformdirsimport*>>> 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/.local/state/SuperApp/log'>>> user_config_dir(appname)'/home/trentm/.config/SuperApp'>>> user_documents_dir()'/home/trentm/Documents'>>> user_downloads_dir()'/home/trentm/Downloads'>>> user_pictures_dir()'/home/trentm/Pictures'>>> user_videos_dir()'/home/trentm/Videos'>>> user_music_dir()'/home/trentm/Music'>>> user_desktop_dir()'/home/trentm/Desktop'>>> 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.myApp/files/SuperApp'>>> user_cache_dir(appname, appauthor)'/data/data/com.myApp/cache/SuperApp'>>> user_log_dir(appname, appauthor)'/data/data/com.myApp/cache/SuperApp/log'>>> user_config_dir(appname)'/data/data/com.myApp/shared_prefs/SuperApp'>>> user_documents_dir()'/storage/emulated/0/Documents'>>> user_downloads_dir()'/storage/emulated/0/Downloads'>>> user_pictures_dir()'/storage/emulated/0/Pictures'>>> user_videos_dir()'/storage/emulated/0/DCIM/Camera'>>> user_music_dir()'/storage/emulated/0/Music'>>> user_desktop_dir()'/storage/emulated/0/Desktop'>>> user_runtime_dir(appname, appauthor)'/data/data/com.myApp/cache/SuperApp/tmp'

Note: Some android apps like Termux and Pydroid are used as shells. Theseapps are used by the end user to emulate Linux environment. Presence ofSHELL environment variable is used by Platformdirs to differentiatebetween general android apps and android apps used as shells. Shell androidapps also supportXDG_* environment variables.

>>>from platformdirsimport 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_downloads_dir'/Users/trentm/Downloads'>>> dirs.user_pictures_dir'/Users/trentm/Pictures'>>> dirs.user_videos_dir'/Users/trentm/Movies'>>> dirs.user_music_dir'/Users/trentm/Music'>>> dirs.user_desktop_dir'/Users/trentm/Desktop'>>> dirs.user_runtime_dir'/Users/trentm/Library/Caches/TemporaryItems/SuperApp'

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

>>> 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_downloads_dir'/Users/trentm/Downloads'>>> dirs.user_pictures_dir'/Users/trentm/Pictures'>>> dirs.user_videos_dir'/Users/trentm/Movies'>>> dirs.user_music_dir'/Users/trentm/Music'>>> dirs.user_desktop_dir'/Users/trentm/Desktop'>>> 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 handlemigrating configuration files manually.

This repository is a friendly fork of the wonderful work started byActiveState who createdappdirs, this package's ancestor.

Maintaining an open source project is no easy task, particularlyfrom within an organization, and the Python community is indebtedtoappdirs (and to Trent Mick and Jeff Rouse in particular) forcreating an incredibly useful simple module, as evidenced by the widenumber of users it has attracted over the years.

Nonetheless, given the number of long-standing open issuesand pull requests, and no clear path towardsensuringthat maintenance of the package would continue or grow, this fork wascreated.

Contributions are most welcome.