Install & Compatibility
Where this runs
tested against v0.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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}")
Debug
Known issues
breakingThe 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.fixMigrate your application's directory logic from `appdirs` to `platformdirs`. Uninstall `appdirs-stubs` and `appdirs`, then `pip install platformdirs`.
affects: <=1.4.4 (for appdirs)
deprecatedThe 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.fixTransition 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`.
affects: All versions
gotchaThe `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.fixThoroughly test your application's directory path resolution on all target operating systems and configurations. Consult the `appdirs` (or `platformdirs`) documentation for detailed path behaviors.
affects: All versions
Errors
Common errors & fixes
Module 'appdirs' has no attribute 'some_new_function_or_attribute'
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`.
fixCheck 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)
This error typically occurs if `appdirs` is installed but `appdirs-stubs` is not, and your type checker is configured to report missing type stubs.
fixInstall the `appdirs-stubs` package: `pip install appdirs-stubs`. If you are using `platformdirs` instead of `appdirs`, ensure `appdirs` is uninstalled.
Upgrade
Version history
0.2.0latest on PyPI · released Jan 10, 2026
Audit
Dependencies
appdirsrequiredRuntime library for which these are type stubs.