Tutorial

In this tutorial, we will set up platformdirs for a small application that stores user preferences, caches API responses, and writes log files – all to the correct platform-specific directories.

Installation

Install platformdirs from PyPI:

$ pip install platformdirs

Verify the installation:

>>> import platformdirs
>>> platformdirs.__version__
'...'

Finding your first directory

Let’s find where our application should store its data. Open a Python shell and run:

>>> from platformdirs import user_data_dir
>>> user_data_dir("MyApp", "AcmeCompany")
'...'

The result depends on the platform you’re running on:

macOS

'/Users/<you>/Library/Application Support/MyApp'

Linux

'/home/<you>/.local/share/MyApp'

Windows

'C:\\Users\\<you>\\AppData\\Local\\AcmeCompany\\MyApp'

Notice on Windows the path includes both the author (AcmeCompany) and the app name (MyApp). If we omit appauthor, it defaults to appname, producing AppData\Local\MyApp\MyApp. To get a flat AppData\Local\MyApp, pass appauthor=False:

>>> user_data_dir("MyApp", appauthor=False)  # on Windows
'C:\\Users\\<you>\\AppData\\Local\\MyApp'

Each function returns a str. If we prefer a Path, we use the _path variant:

>>> from platformdirs import user_data_path
>>> user_data_path("MyApp", "AcmeCompany")
PosixPath('...')

Now let’s find the cache directory:

>>> from platformdirs import user_cache_dir
>>> user_cache_dir("MyApp", "AcmeCompany")
'...'

And the log directory:

>>> from platformdirs import user_log_dir
>>> user_log_dir("MyApp", "AcmeCompany")
'...'

Each directory type resolves to a different location, following the conventions of the current platform.

Working with multiple directories

When we need several directories for the same application, importing individual functions becomes verbose. Instead, we instantiate PlatformDirs once and access its properties:

>>> from platformdirs import PlatformDirs
>>> dirs = PlatformDirs("MyApp", "AcmeCompany")
>>> dirs.user_data_dir
'...'
>>> dirs.user_config_dir
'...'
>>> dirs.user_cache_dir
'...'
>>> dirs.user_log_dir
'...'

Every str property has a corresponding _path property:

>>> dirs.user_data_path
PosixPath('...')
>>> dirs.user_cache_path
PosixPath('...')

We can also have platformdirs create the directories for us by setting ensure_exists=True:

>>> dirs = PlatformDirs("MyApp", "AcmeCompany", ensure_exists=True)
>>> dirs.user_data_dir  # directory is created if it doesn't exist
'...'

Complete example

Let’s put it all together. We will build a small application class that uses config, cache, data, and log directories:

import json
import logging
from pathlib import Path

from platformdirs import PlatformDirs


class MyApp:
    def __init__(self) -> None:
        dirs = PlatformDirs("MyApp", "AcmeCompany", ensure_exists=True)

        # Persistent data (database, downloads)
        self.db_path = dirs.user_data_path / "app.db"

        # User configuration
        self.config_path = dirs.user_config_path / "settings.json"

        # Cache for performance
        self.cache_dir = dirs.user_cache_path

        # Application logs
        log_file = dirs.user_log_path / "app.log"
        logging.basicConfig(filename=log_file, level=logging.INFO)

        # Window state and UI preferences
        self.state_path = dirs.user_state_path / "window.json"

    def load_config(self) -> dict:
        if self.config_path.exists():
            return json.loads(self.config_path.read_text())
        return {"theme": "light", "autosave": True}

We can verify that it works:

>>> app = MyApp()
>>> app.config_path
PosixPath('...')
>>> app.db_path
PosixPath('...')

Each directory is created automatically and follows the platform conventions.

What you’ve learned

• platformdirs resolves the correct directory for each platform automatically.

• Standalone functions like user_data_dir return a single directory as a str.

• The _path variants return Path objects.

• The PlatformDirs class provides all directories from a single instance.

• ensure_exists=True creates directories on first access.

Where to go next

• How-to guides – recipes for common tasks like error handling, cache cleanup, and testing.

• Understanding platformdirs – understand why different directory types exist and how each platform works.

• Parameter reference – full reference for all parameters (appname, version, roaming, etc.).

• API – complete API documentation.

• Platform details – exact paths for every directory on every platform.