appdirs-stubs

0.2.0 · maintenance · verified Thu Apr 16

Type stubs for the `appdirs` library, providing static type checking support for code using `appdirs`. This helps tools like MyPy, PyRight, and PyCharm analyze `appdirs` usage. While `appdirs-stubs` is currently maintained (latest version 0.2.0, released Jan 10, 2026), the underlying `appdirs` library has been officially deprecated since 2020 in favor of `platformdirs`.

Common errors

```
Module 'appdirs' has no attribute 'some_new_function_or_attribute'
```
cause The `appdirs` library was updated with a new function or attribute, but `appdirs-stubs` has not yet been updated to reflect these changes. This is more likely now given the deprecation of `appdirs`.

fix Check if an update to `appdirs-stubs` is available (`pip install --upgrade appdirs-stubs`). If not, consider migrating to `platformdirs` which is actively maintained and ships with its own types. Alternatively, use a `# type: ignore` comment if the missing stub is not critical for your type checks.
```
error: Library 'appdirs' has no type annotations or stubs (reportMissingTypeStubs)
```
cause This error typically occurs if `appdirs` is installed but `appdirs-stubs` is not, and your type checker is configured to report missing type stubs.

fix Install the `appdirs-stubs` package: `pip install appdirs-stubs`. If you are using `platformdirs` instead of `appdirs`, ensure `appdirs` is uninstalled.

Warnings

breaking The underlying `appdirs` library is officially deprecated since 2020. Users are strongly encouraged to migrate to `platformdirs` which is a more active fork and includes its own `py.typed` file for type hinting out-of-the-box, eliminating the need for separate stub packages.
Fix: Migrate your application's directory logic from `appdirs` to `platformdirs`. Uninstall `appdirs-stubs` and `appdirs`, then `pip install platformdirs`.
deprecated The official `types-appdirs` package from Typeshed is unmaintained and will not receive further updates or fixes for type issues or new features in `appdirs`. While `appdirs-stubs` is a separate, maintained alternative, its utility is limited by the deprecation of `appdirs` itself.
Fix: Transition to `platformdirs` as the primary solution for platform-specific directory needs and its built-in type information. This removes reliance on external stub packages for `appdirs`.
gotcha The `appdirs` functions (e.g., `user_data_dir`) can return different paths depending on the operating system, presence of environment variables (like XDG spec on Unix), and arguments like `appname`, `appauthor`, `version`, and `roaming`. This behavior is at runtime and not typically caught by type checkers.
Fix: Thoroughly test your application's directory path resolution on all target operating systems and configurations. Consult the `appdirs` (or `platformdirs`) documentation for detailed path behaviors.

Install

pip install appdirs-stubs Install with pip

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
```
site_config_dir
```
from appdirs import site_config_dir
```
user_log_dir
```
from appdirs import user_log_dir
```
AppDirs
```
from appdirs import AppDirs
```
Class-based access to appdir functions.

Quickstart

Demonstrates importing and using `appdirs` functions with type hints, including an `if TYPE_CHECKING` block to illustrate type-checking functionality with the stubs.

from appdirs import user_data_dir
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    # This block is only for type checkers and helps verify stub correctness
    appname: str = "MyApplication"
    appauthor: str = "MyCompany"
    data_path: str = user_data_dir(appname, appauthor)
    # Example: Check if the return type is str
    reveal_type(data_path)

# Runtime usage of appdirs (requires 'appdirs' package installed)
app_name_runtime = "MyAwesomeApp"
app_author_runtime = "CoolDevs"
runtime_data_path = user_data_dir(app_name_runtime, app_author_runtime)
print(f"User data directory: {runtime_data_path}")

view raw JSON →