{"id":15204963,"url":"https://github.com/tox-dev/platformdirs","last_synced_at":"2026-02-14T03:56:34.913Z","repository":{"id":37941335,"uuid":"367032142","full_name":"tox-dev/platformdirs","owner":"tox-dev","description":"A small Python module for determining appropriate platform-specific dirs, e.g. a \"user data dir\".","archived":false,"fork":false,"pushed_at":"2025-04-21T16:44:04.000Z","size":504,"stargazers_count":709,"open_issues_count":16,"forks_count":57,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-22T02:45:57.512Z","etag":null,"topics":["appdirs","configuration","cross-platform","hacktoberfest","xdg","xdg-user-dirs"],"latest_commit_sha":null,"homepage":"https://platformdirs.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tox-dev.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"tidelift":"pypi/platformdirs"}},"created_at":"2021-05-13T11:48:19.000Z","updated_at":"2025-04-20T22:53:31.000Z","dependencies_parsed_at":"2023-02-19T12:15:22.086Z","dependency_job_id":"625e5688-1ea6-41b6-8bde-d10cfe5f66fa","html_url":"https://github.com/tox-dev/platformdirs","commit_stats":{"total_commits":422,"total_committers":80,"mean_commits":5.275,"dds":0.8459715639810427,"last_synced_commit":"2bf1ba47dae2251e8b3f3cfe7977df41bd24969c"},"previous_names":["tox-dev/platformdirs","platformdirs/platformdirs"],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Fplatformdirs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Fplatformdirs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Fplatformdirs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Fplatformdirs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tox-dev","download_url":"https://codeload.github.com/tox-dev/platformdirs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250490477,"owners_count":21439152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["appdirs","configuration","cross-platform","hacktoberfest","xdg","xdg-user-dirs"],"created_at":"2024-09-28T06:01:02.715Z","updated_at":"2025-12-11T21:04:12.032Z","avatar_url":"https://github.com/tox-dev.png","language":"Python","readme":"The problem\n===========\n\n.. image:: https://badge.fury.io/py/platformdirs.svg\n   :target: https://badge.fury.io/py/platformdirs\n.. image:: https://img.shields.io/pypi/pyversions/platformdirs.svg\n   :target: https://pypi.python.org/pypi/platformdirs/\n.. image:: https://github.com/tox-dev/platformdirs/actions/workflows/check.yaml/badge.svg\n   :target: https://github.com/platformdirs/platformdirs/actions\n.. image:: https://static.pepy.tech/badge/platformdirs/month\n   :target: https://pepy.tech/project/platformdirs\n\nWhen writing desktop application, finding the right location to store user data\nand configuration varies per platform. Even for single-platform apps, there\nmay by plenty of nuances in figuring out the right location.\n\nFor example, if running on macOS, you should use::\n\n    ~/Library/Application Support/\u003cAppName\u003e\n\nIf on Windows (at least English Win) that should be::\n\n    C:\\Users\\\u003cUser\u003e\\Application Data\\Local Settings\\\u003cAppAuthor\u003e\\\u003cAppName\u003e\n\nor possibly::\n\n    C:\\Users\\\u003cUser\u003e\\Application Data\\\u003cAppAuthor\u003e\\\u003cAppName\u003e\n\nfor `roaming profiles \u003chttps://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-vista/cc766489(v=ws.10)\u003e`_ but that is another story.\n\nOn Linux (and other Unices), according to the `XDG Basedir Spec`_, it should be::\n\n    ~/.local/share/\u003cAppName\u003e\n\n.. _XDG Basedir Spec: https://specifications.freedesktop.org/basedir/latest/\n\n``platformdirs`` to the rescue\n==============================\n\nThis kind of thing is what the ``platformdirs`` package is for.\n``platformdirs`` will help you choose an appropriate:\n\n- user data dir (``user_data_dir``)\n- user config dir (``user_config_dir``)\n- user cache dir (``user_cache_dir``)\n- site data dir (``site_data_dir``)\n- site config dir (``site_config_dir``)\n- user log dir (``user_log_dir``)\n- user documents dir (``user_documents_dir``)\n- user downloads dir (``user_downloads_dir``)\n- user pictures dir (``user_pictures_dir``)\n- user videos dir (``user_videos_dir``)\n- user music dir (``user_music_dir``)\n- user desktop dir (``user_desktop_dir``)\n- user runtime dir (``user_runtime_dir``)\n\nAnd also:\n\n- Is slightly opinionated on the directory names used. Look for \"OPINION\" in\n  documentation and code for when an opinion is being applied.\n\nExample output\n==============\n\nOn macOS:\n\n.. code-block:: pycon\n\n    \u003e\u003e\u003e from platformdirs import *\n    \u003e\u003e\u003e appname = \"SuperApp\"\n    \u003e\u003e\u003e appauthor = \"Acme\"\n    \u003e\u003e\u003e user_data_dir(appname, appauthor)\n    '/Users/trentm/Library/Application Support/SuperApp'\n    \u003e\u003e\u003e user_config_dir(appname, appauthor)\n    '/Users/trentm/Library/Application Support/SuperApp'\n    \u003e\u003e\u003e user_cache_dir(appname, appauthor)\n    '/Users/trentm/Library/Caches/SuperApp'\n    \u003e\u003e\u003e site_data_dir(appname, appauthor)\n    '/Library/Application Support/SuperApp'\n    \u003e\u003e\u003e site_config_dir(appname, appauthor)\n    '/Library/Application Support/SuperApp'\n    \u003e\u003e\u003e user_log_dir(appname, appauthor)\n    '/Users/trentm/Library/Logs/SuperApp'\n    \u003e\u003e\u003e user_documents_dir()\n    '/Users/trentm/Documents'\n    \u003e\u003e\u003e user_downloads_dir()\n    '/Users/trentm/Downloads'\n    \u003e\u003e\u003e user_pictures_dir()\n    '/Users/trentm/Pictures'\n    \u003e\u003e\u003e user_videos_dir()\n    '/Users/trentm/Movies'\n    \u003e\u003e\u003e user_music_dir()\n    '/Users/trentm/Music'\n    \u003e\u003e\u003e user_desktop_dir()\n    '/Users/trentm/Desktop'\n    \u003e\u003e\u003e user_runtime_dir(appname, appauthor)\n    '/Users/trentm/Library/Caches/TemporaryItems/SuperApp'\n\nOn Windows:\n\n.. code-block:: pycon\n\n    \u003e\u003e\u003e from platformdirs import *\n    \u003e\u003e\u003e appname = \"SuperApp\"\n    \u003e\u003e\u003e appauthor = \"Acme\"\n    \u003e\u003e\u003e user_data_dir(appname, appauthor)\n    'C:\\\\Users\\\\trentm\\\\AppData\\\\Local\\\\Acme\\\\SuperApp'\n    \u003e\u003e\u003e user_data_dir(appname, appauthor, roaming=True)\n    'C:\\\\Users\\\\trentm\\\\AppData\\\\Roaming\\\\Acme\\\\SuperApp'\n    \u003e\u003e\u003e user_config_dir(appname, appauthor)\n    'C:\\\\Users\\\\trentm\\\\AppData\\\\Local\\\\Acme\\\\SuperApp'\n    \u003e\u003e\u003e user_cache_dir(appname, appauthor)\n    'C:\\\\Users\\\\trentm\\\\AppData\\\\Local\\\\Acme\\\\SuperApp\\\\Cache'\n    \u003e\u003e\u003e site_data_dir(appname, appauthor)\n    'C:\\\\ProgramData\\\\Acme\\\\SuperApp'\n    \u003e\u003e\u003e site_config_dir(appname, appauthor)\n    'C:\\\\ProgramData\\\\Acme\\\\SuperApp'\n    \u003e\u003e\u003e user_log_dir(appname, appauthor)\n    'C:\\\\Users\\\\trentm\\\\AppData\\\\Local\\\\Acme\\\\SuperApp\\\\Logs'\n    \u003e\u003e\u003e user_documents_dir()\n    'C:\\\\Users\\\\trentm\\\\Documents'\n    \u003e\u003e\u003e user_downloads_dir()\n    'C:\\\\Users\\\\trentm\\\\Downloads'\n    \u003e\u003e\u003e user_pictures_dir()\n    'C:\\\\Users\\\\trentm\\\\Pictures'\n    \u003e\u003e\u003e user_videos_dir()\n    'C:\\\\Users\\\\trentm\\\\Videos'\n    \u003e\u003e\u003e user_music_dir()\n    'C:\\\\Users\\\\trentm\\\\Music'\n    \u003e\u003e\u003e user_desktop_dir()\n    'C:\\\\Users\\\\trentm\\\\Desktop'\n    \u003e\u003e\u003e user_runtime_dir(appname, appauthor)\n    'C:\\\\Users\\\\trentm\\\\AppData\\\\Local\\\\Temp\\\\Acme\\\\SuperApp'\n\nOn Linux:\n\n.. code-block:: pycon\n\n    \u003e\u003e\u003e from platformdirs import *\n    \u003e\u003e\u003e appname = \"SuperApp\"\n    \u003e\u003e\u003e appauthor = \"Acme\"\n    \u003e\u003e\u003e user_data_dir(appname, appauthor)\n    '/home/trentm/.local/share/SuperApp'\n    \u003e\u003e\u003e user_config_dir(appname)\n    '/home/trentm/.config/SuperApp'\n    \u003e\u003e\u003e user_cache_dir(appname, appauthor)\n    '/home/trentm/.cache/SuperApp'\n    \u003e\u003e\u003e site_data_dir(appname, appauthor)\n    '/usr/local/share/SuperApp'\n    \u003e\u003e\u003e site_data_dir(appname, appauthor, multipath=True)\n    '/usr/local/share/SuperApp:/usr/share/SuperApp'\n    \u003e\u003e\u003e site_config_dir(appname)\n    '/etc/xdg/SuperApp'\n    \u003e\u003e\u003e os.environ[\"XDG_CONFIG_DIRS\"] = \"/etc:/usr/local/etc\"\n    \u003e\u003e\u003e site_config_dir(appname, multipath=True)\n    '/etc/SuperApp:/usr/local/etc/SuperApp'\n    \u003e\u003e\u003e user_log_dir(appname, appauthor)\n    '/home/trentm/.local/state/SuperApp/log'\n    \u003e\u003e\u003e user_documents_dir()\n    '/home/trentm/Documents'\n    \u003e\u003e\u003e user_downloads_dir()\n    '/home/trentm/Downloads'\n    \u003e\u003e\u003e user_pictures_dir()\n    '/home/trentm/Pictures'\n    \u003e\u003e\u003e user_videos_dir()\n    '/home/trentm/Videos'\n    \u003e\u003e\u003e user_music_dir()\n    '/home/trentm/Music'\n    \u003e\u003e\u003e user_desktop_dir()\n    '/home/trentm/Desktop'\n    \u003e\u003e\u003e user_runtime_dir(appname, appauthor)\n    '/run/user/{os.getuid()}/SuperApp'\n\nOn Android::\n\n    \u003e\u003e\u003e from platformdirs import *\n    \u003e\u003e\u003e appname = \"SuperApp\"\n    \u003e\u003e\u003e appauthor = \"Acme\"\n    \u003e\u003e\u003e user_data_dir(appname, appauthor)\n    '/data/data/com.myApp/files/SuperApp'\n    \u003e\u003e\u003e user_config_dir(appname)\n    '/data/data/com.myApp/shared_prefs/SuperApp'\n    \u003e\u003e\u003e user_cache_dir(appname, appauthor)\n    '/data/data/com.myApp/cache/SuperApp'\n    \u003e\u003e\u003e site_data_dir(appname, appauthor)\n    '/data/data/com.myApp/files/SuperApp'\n    \u003e\u003e\u003e site_config_dir(appname)\n    '/data/data/com.myApp/shared_prefs/SuperApp'\n    \u003e\u003e\u003e user_log_dir(appname, appauthor)\n    '/data/data/com.myApp/cache/SuperApp/log'\n    \u003e\u003e\u003e user_documents_dir()\n    '/storage/emulated/0/Documents'\n    \u003e\u003e\u003e user_downloads_dir()\n    '/storage/emulated/0/Downloads'\n    \u003e\u003e\u003e user_pictures_dir()\n    '/storage/emulated/0/Pictures'\n    \u003e\u003e\u003e user_videos_dir()\n    '/storage/emulated/0/DCIM/Camera'\n    \u003e\u003e\u003e user_music_dir()\n    '/storage/emulated/0/Music'\n    \u003e\u003e\u003e user_desktop_dir()\n    '/storage/emulated/0/Desktop'\n    \u003e\u003e\u003e user_runtime_dir(appname, appauthor)\n    '/data/data/com.myApp/cache/SuperApp/tmp'\n\nNote: Some android apps like Termux and Pydroid are used as shells. These\napps are used by the end user to emulate Linux environment. Presence of\n``SHELL`` environment variable is used by Platformdirs to differentiate\nbetween general android apps and android apps used as shells. Shell android\napps also support ``XDG_*`` environment variables.\n\n\n``PlatformDirs`` for convenience\n================================\n\n.. code-block:: pycon\n\n    \u003e\u003e\u003e from platformdirs import PlatformDirs\n    \u003e\u003e\u003e dirs = PlatformDirs(\"SuperApp\", \"Acme\")\n    \u003e\u003e\u003e dirs.user_data_dir\n    '/Users/trentm/Library/Application Support/SuperApp'\n    \u003e\u003e\u003e dirs.user_config_dir\n    '/Users/trentm/Library/Application Support/SuperApp'\n    \u003e\u003e\u003e dirs.user_cache_dir\n    '/Users/trentm/Library/Caches/SuperApp'\n    \u003e\u003e\u003e dirs.site_data_dir\n    '/Library/Application Support/SuperApp'\n    \u003e\u003e\u003e dirs.site_config_dir\n    '/Library/Application Support/SuperApp'\n    \u003e\u003e\u003e dirs.user_cache_dir\n    '/Users/trentm/Library/Caches/SuperApp'\n    \u003e\u003e\u003e dirs.user_log_dir\n    '/Users/trentm/Library/Logs/SuperApp'\n    \u003e\u003e\u003e dirs.user_documents_dir\n    '/Users/trentm/Documents'\n    \u003e\u003e\u003e dirs.user_downloads_dir\n    '/Users/trentm/Downloads'\n    \u003e\u003e\u003e dirs.user_pictures_dir\n    '/Users/trentm/Pictures'\n    \u003e\u003e\u003e dirs.user_videos_dir\n    '/Users/trentm/Movies'\n    \u003e\u003e\u003e dirs.user_music_dir\n    '/Users/trentm/Music'\n    \u003e\u003e\u003e dirs.user_desktop_dir\n    '/Users/trentm/Desktop'\n    \u003e\u003e\u003e dirs.user_runtime_dir\n    '/Users/trentm/Library/Caches/TemporaryItems/SuperApp'\n\nPer-version isolation\n=====================\n\nIf you have multiple versions of your app in use that you want to be\nable to run side-by-side, then you may want version-isolation for these\ndirs::\n\n    \u003e\u003e\u003e from platformdirs import PlatformDirs\n    \u003e\u003e\u003e dirs = PlatformDirs(\"SuperApp\", \"Acme\", version=\"1.0\")\n    \u003e\u003e\u003e dirs.user_data_dir\n    '/Users/trentm/Library/Application Support/SuperApp/1.0'\n    \u003e\u003e\u003e dirs.user_config_dir\n    '/Users/trentm/Library/Application Support/SuperApp/1.0'\n    \u003e\u003e\u003e dirs.user_cache_dir\n    '/Users/trentm/Library/Caches/SuperApp/1.0'\n    \u003e\u003e\u003e dirs.site_data_dir\n    '/Library/Application Support/SuperApp/1.0'\n    \u003e\u003e\u003e dirs.site_config_dir\n    '/Library/Application Support/SuperApp/1.0'\n    \u003e\u003e\u003e dirs.user_log_dir\n    '/Users/trentm/Library/Logs/SuperApp/1.0'\n    \u003e\u003e\u003e dirs.user_documents_dir\n    '/Users/trentm/Documents'\n    \u003e\u003e\u003e dirs.user_downloads_dir\n    '/Users/trentm/Downloads'\n    \u003e\u003e\u003e dirs.user_pictures_dir\n    '/Users/trentm/Pictures'\n    \u003e\u003e\u003e dirs.user_videos_dir\n    '/Users/trentm/Movies'\n    \u003e\u003e\u003e dirs.user_music_dir\n    '/Users/trentm/Music'\n    \u003e\u003e\u003e dirs.user_desktop_dir\n    '/Users/trentm/Desktop'\n    \u003e\u003e\u003e dirs.user_runtime_dir\n    '/Users/trentm/Library/Caches/TemporaryItems/SuperApp/1.0'\n\nBe wary of using this for configuration files though; you'll need to handle\nmigrating configuration files manually.\n\nWhy this Fork?\n==============\n\nThis repository is a friendly fork of the wonderful work started by\n`ActiveState \u003chttps://github.com/ActiveState/appdirs\u003e`_ who created\n``appdirs``, this package's ancestor.\n\nMaintaining an open source project is no easy task, particularly\nfrom within an organization, and the Python community is indebted\nto ``appdirs`` (and to Trent Mick and Jeff Rouse in particular) for\ncreating an incredibly useful simple module, as evidenced by the wide\nnumber of users it has attracted over the years.\n\nNonetheless, given the number of long-standing open issues\nand pull requests, and no clear path towards `ensuring\nthat maintenance of the package would continue or grow\n\u003chttps://github.com/ActiveState/appdirs/issues/79\u003e`_, this fork was\ncreated.\n\nContributions are most welcome.\n","funding_links":["https://tidelift.com/funding/github/pypi/platformdirs"],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftox-dev%2Fplatformdirs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftox-dev%2Fplatformdirs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftox-dev%2Fplatformdirs/lists"}