Registry / devops / pystow

pystow

JSON →
library0.8.17pypypi✓ verified 87d ago

PyStow is a Python library that simplifies the process of picking a consistent and predictable location for storing data generated or consumed by your Python code. It helps manage application data directories and ensures their existence, often defaulting to a structured `$HOME/.data/<app_name>` path. The current version is 0.8.3, and it maintains an active development and release cadence, with version 0.8.4-dev also documented.

pip install pystow
INSTALL
IMPORT
SIG · PYSTOW
P
pystow
devopspythonv0.8.17
Install
2.0s avg
Import
470ms
Disk
19MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.8.17 · 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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.494s · 20.9MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.0s · import 0.447s · 21MB
19MB installed
● package 19MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

pystow
import pystow

This quickstart demonstrates how to use `pystow.join` to get and create application-specific directories, and `pystow.ensure` to download and store a file, ensuring its presence. It also shows the `pystow.module` pattern. A temporary custom `PYSTOW_HOME` is set for isolated testing, which defaults to `$HOME/.data` if not configured.

import pystow import os # Configure a custom base directory for PyStow (optional, for testing/isolation) # Defaults to ~/.data if not set os.environ['PYSTOW_HOME'] = os.path.join(os.getcwd(), 'my_pystow_data') # Get a directory for your application data app_dir = pystow.join('my_app') print(f"Application data directory: {app_dir}") app_dir.mkdir(parents=True, exist_ok=True) # Ensure a file is downloaded from a URL into a specific subdirectory url = 'https://raw.githubusercontent.com/pykeen/pykeen/master/src/pykeen/datasets/nations/test.txt' file_path = pystow.ensure( 'my_app', 'datasets', 'nations', url=url, name='nations_test.txt' ) print(f"Ensured file path: {file_path}") # You can also use modules for cleaner access my_app_module = pystow.module('my_app') module_file_path = my_app_module.ensure( 'another_data', url='https://example.com/some_file.txt', name='some_file.txt' # This URL is a placeholder and will likely fail. ) print(f"Ensured file via module: {module_file_path}") # Clean up the custom directory for demonstration # import shutil # if os.path.exists(os.environ['PYSTOW_HOME']): # shutil.rmtree(os.environ['PYSTOW_HOME']) # del os.environ['PYSTOW_HOME']
Debug
Known issues
gotchaPyStow defaults to storing data in `$HOME/.data/`. This can be overridden globally by setting the `PYSTOW_HOME` environment variable, or by enabling XDG compatibility with `PYSTOW_USE_APPDIRS=True`, which uses `appdirs` or `platformdirs`.
fix
To control the base directory, set `PYSTOW_HOME` environment variable (e.g., `os.environ['PYSTOW_HOME'] = '/path/to/data'`) or `PYSTOW_USE_APPDIRS='True'` for XDG compliance. Ensure your application explicitly checks or sets these if a specific data location is critical.
affects: All versions
gotchaAs of version 0.8.3, PyStow does not ship with a `py.typed` file, leading to `mypy` and other static type checkers skipping its analysis and reporting 'missing library stubs or py.typed marker' errors.
fix
There is no direct fix for users within the library. If strict type checking is required for your project, you might need to add `pystow` to `mypy`'s `[mypy-pystow*]` section with `ignore_missing_imports = True` in your `mypy.ini` or similar configuration.
affects: <=0.8.3
gotchaWhen using `pystow.ensure`, especially with `name` argument, be aware that the `name` overrides the filename derived from the URL. If the URL does not have a proper filename, `name` is essential, but if it does, `name` changes it. Ensure the `name` matches your expectation for the downloaded file.
fix
Always explicitly define the `name` argument in `pystow.ensure` if you have a specific filename expectation, especially for URLs that might not have a clean filename component. Review the resulting `Path` object to confirm the filename is as expected.
affects: All versions
Errors
Common errors & fixes
Skipping analyzing "pystow": module is installed, but missing library stubs or py.typed marker
PyStow does not currently include a `py.typed` file in its distribution, which is necessary for static type checkers like `mypy` to properly analyze the library's types.
fix
Add `ignore_missing_imports = True` for `pystow` in your `mypy` configuration (e.g., in `mypy.ini` under `[mypy-pystow*]`) to suppress this error and allow `mypy` to continue checking the rest of your project.
FileNotFoundError: [Errno 2] No such file or directory: '/some/unexpected/path/my_app/data.txt'
The application is trying to access a file or directory managed by PyStow, but PyStow's base directory or a specific subdirectory was not created, or an environment variable (like `PYSTOW_HOME`) is pointing to a non-existent or inaccessible location.
fix
Ensure that `pystow.join()` or `pystow.module()` calls are properly made, which automatically create directories. Verify that the `PYSTOW_HOME` environment variable (if set) points to a valid and writable location. Check application logs for any `pystow`-related path resolution issues.
Upgrade
Version history
0.8.17latest on PyPI · released Jun 15, 2026
Audit
Dependencies
pandasoptionalRequired for `ensure_csv`, `ensure_excel`, `load_df`, and other DataFrame-related I/O utilities.
platformdirsoptionalUsed for XDG Base Directory Specification compatibility when `PYSTOW_USE_APPDIRS` is enabled.
Agent activity
4 hits · last 30 days
node
4
Resources
pystow — pip install pystow · libregistry