types-appdirs (Type Stubs for appdirs)

Common errors

• TypeError: unexpected keyword argument 'appversion'

  cause Using the keyword argument `appversion` instead of `version` when calling `appdirs` functions (e.g., `user_data_dir`).
  fix Change `appversion=some_version` to `version=some_version` in your function calls. Example: `user_data_dir(appname, appauthor, version='1.0')`.

• ModuleNotFoundError: No module named 'appdirs'

  cause The `appdirs` runtime library is not installed. `types-appdirs` only provides type stubs, not the actual implementation.
  fix Install the `appdirs` package: `pip install appdirs`.

• PathNotFoundException (or similar OS error) when trying to write to an appdirs path.

  cause The directories returned by `appdirs` functions are just strings representing paths; `appdirs` does not create these directories on the filesystem automatically.
  fix Manually create the directory (and any necessary parent directories) using `os.makedirs(path, exist_ok=True)` before attempting to write files to it.

Warnings

• deprecated The `types-appdirs` package is unmaintained and deprecated. The underlying `appdirs` library is also deprecated. Users should migrate to `platformdirs` which is an actively maintained fork and includes its own type information, removing the need for separate stubs.
  Fix: Migrate your application from `appdirs` to `platformdirs`. The API is largely compatible, making migration straightforward. Remove `types-appdirs` after migration.
• breaking Functions like `user_data_dir`, `user_config_dir`, etc., in `appdirs` expect the application version argument to be named `version`, not `appversion`. Using `appversion` will result in a `TypeError: unexpected keyword argument`.
  Fix: Correct the keyword argument from `appversion` to `version` when calling `appdirs` functions (e.g., `user_data_dir(appname, appauthor, version='1.0')`).
• gotcha `appdirs` is 'slightly opinionated' on directory names. The exact paths generated can sometimes differ from strict system conventions or other tools' interpretations, potentially adding specific suffixes to directory names.
  Fix: Always verify the generated paths on your target operating systems. If `appdirs`'s default naming is problematic, consider examining the `platformdirs` documentation for more flexible options or implementing custom logic. You can sometimes disable opinionated behavior with `opinion=False` where available (e.g., `user_log_dir`).
• gotcha Older `appdirs` 1.x releases (e.g., 1.4.1) had specific issues with Python 3, particularly concerning Windows registry access (`winreg`) and string handling. These were addressed in subsequent minor releases.
  Fix: Ensure you are using at least `appdirs==1.4.4` for Python 3 environments. For the best compatibility and ongoing support, migrate to `platformdirs`.

Install

• pip install types-appdirs Install types-appdirs
• pip install appdirs Install runtime dependency (appdirs)

Imports

• user_data_dir

  from appdirs import user_data_dir

• user_config_dir

  from appdirs import user_config_dir

• user_cache_dir

  from appdirs import user_cache_dir

• site_data_dir

  from appdirs import site_data_dir

• AppDirs
  wrong:

  from types_appdirs import AppDirs

  correct:

  from appdirs import AppDirs

  types-appdirs provides stubs for the appdirs library, so you import from 'appdirs' directly.

Quickstart

This quickstart demonstrates how to use `appdirs` (for which `types-appdirs` provides stubs) to retrieve common application-specific directory paths for the current user and platform. It also shows how to create one of these directories, as `appdirs` only provides the path strings.

from appdirs import user_data_dir, user_config_dir, user_cache_dir
import os

appname = "MyAwesomeApp"
appauthor = "MyCompany"

# Get user-specific data directory
data_dir = user_data_dir(appname, appauthor)
print(f"User Data Directory: {data_dir}")

# Get user-specific configuration directory
config_dir = user_config_dir(appname, appauthor)
print(f"User Config Directory: {config_dir}")

# Get user-specific cache directory
cache_dir = user_cache_dir(appname, appauthor, version="1.0")
print(f"User Cache Directory (v1.0): {cache_dir}")

# Create a directory if it doesn't exist (appdirs does not create paths automatically)
os.makedirs(data_dir, exist_ok=True)
print(f"Ensured data directory exists: {data_dir}")