Registry / http-networking / cached-path

cached-path

library1.8.10pypypi✓ verified 26d ago

cached-path is a Python file utility library that provides a unified, simple interface for accessing both local and remote files. It automatically downloads and caches remote resources, making them available as local file paths. Currently at version 1.8.10, the library maintains an active development pace with frequent patch and minor releases to address compatibility and add new features.

http-networking serialization

pip install cached-path

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · CACHED-PATH

cached-path

http-networkingpythonv1.8.10

Install

10.2s avg

Import

2353ms

Disk

128MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.8.10 · 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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 2.508s · 125.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 10.2s · import 2.198s · 127MB

128MB installed

● package 128MB

Code

Verified usage

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

cached_path

✓ from cached_path import cached_path

get_cache_dir

✓ from cached_path import get_cache_dir

This quickstart demonstrates how to use `cached_path()` to download and cache a remote file, and how to extract an archive. It verifies that the returned paths exist locally.

import os from cached_path import cached_path # Download and cache a remote file remote_url = "https://raw.githubusercontent.com/allenai/cached_path/main/README.md" local_path = cached_path(remote_url) print(f"Cached file path: {local_path}") assert os.path.exists(local_path) # Example with an archive, extracting it archive_url = "https://github.com/allenai/cached_path/releases/download/v0.1.0/cached_path-0.1.0.tar.gz" extracted_dir = cached_path(archive_url, extract_archive=True) print(f"Extracted archive directory: {extracted_dir}") assert os.path.isdir(extracted_dir) # Clean up (optional, for demonstration) # import shutil # shutil.rmtree(os.path.dirname(local_path)) # shutil.rmtree(extracted_dir)

Debug

Known issues

breakingOlder versions of cached-path (pre-1.7.2) had incompatibility issues with `boto3/botocore >=1.37.34`. Upgrading `boto3` or `botocore` without updating `cached-path` could lead to errors when accessing S3 resources.

fix

Upgrade cached-path to version 1.7.2 or later to ensure compatibility with recent `boto3` and `botocore` releases.

affects: <1.7.2

gotchaAs of v1.8.10, the default progress bar output for downloads was changed to write to `stderr` instead of `stdout`. Scripts redirecting `stdout` might no longer capture progress information.

fix

If you rely on capturing download progress, redirect `stderr` instead of `stdout` or configure a custom progress display.

affects: >=1.8.10

gotchaVersion 1.8.9 introduced a fix to ensure filesystem sync (`os.fdatasync`) when replacing temporary files with permanent ones. While a data integrity improvement, it implies that prior versions could be susceptible to data loss or corruption in case of power failure or system crash during a file download/replacement operation.

fix

Upgrade to version 1.8.9 or later to benefit from improved data integrity during file caching operations.

affects: <1.8.9

gotchaMultiple versions (1.6.7, 1.7.3, 1.7.4) added support for newer `HuggingFace-Hub` versions. Using an older `cached-path` with a very new `huggingface-hub` might lead to unexpected behavior or errors when using the `hf://` scheme. Always ensure `cached-path` is kept up-to-date when working with `huggingface-hub`.

fix

Keep `cached-path` updated to the latest version, especially when updating `huggingface-hub`, to ensure full compatibility with the `hf://` scheme.

affects: <1.7.4

gotchaWhen using `extract_archive=True`, `cached_path` extracts the entire archive and returns the path to the extracted directory. To access a specific file or sub-directory within an archive without extracting everything, append `!/path/to/file` to the URL (e.g., `hf://model!config.json`).

fix

Understand the distinction: `extract_archive=True` extracts the full archive, while `url!path/to/file` extracts and points to a specific entry within the archive.

affects: All versions

gotchaThe default cache directory is `~/.cache/cached_path/`. This can be overridden globally via the `CACHED_PATH_CACHE_ROOT` environment variable, programmatically with `set_cache_dir()`, or per-call using the `cache_dir` argument to `cached_path()`. Conflicting settings might lead to unexpected cache locations.

fix

Be explicit about your desired cache directory and understand the precedence: argument > `set_cache_dir()` > environment variable.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'cached_path'

The 'cached-path' library is not installed in the current Python environment, or there's a naming conflict or an incorrect import from another library that previously exposed a 'cached_path' utility.

fix

Install the 'cached-path' library using pip: `pip install cached-path`.

FileNotFoundError: [Errno 2] No such file or directory

The local file path or remote URL provided to `cached_path()` does not exist, is inaccessible due to permissions, or is too long for the operating system (e.g., Windows).

fix

Verify the correctness of the file path or URL. Ensure the file exists and is accessible. For long paths on Windows, consider enabling long path support in the OS or setting a shorter `cache_dir`.

ValueError: When the URL is invalid

The string provided to `cached_path()` is not a valid URL format or does not use one of the supported schemes (e.g., 'http', 'https', 's3', 'gs', 'hf').

fix

Correct the URL string to follow a valid format and ensure it uses a supported scheme as outlined in the `cached-path` documentation.

AttributeError: module 'cached_path' has no attribute 'some_attribute'

The installed version of `cached-path` is incompatible with the code attempting to use it, or a specific attribute or function has been removed, renamed, or is not available in that version.

fix

Check the `cached-path` library's changelog or documentation for the specific version you are using. Update your code to be compatible, or upgrade/downgrade `cached-path` to a compatible version (e.g., `pip install cached-path==X.Y.Z`).

cached-path windows path length limitation

On Windows, the default maximum path length can be exceeded by cached files, leading to silent failures or `FileNotFoundError` when `cached-path` tries to create or access very long paths.

fix

Enable long path support in your Windows OS settings. Alternatively, specify a shorter custom cache directory using `cached_path(url_or_filename, cache_dir='/short/path')` or `cached_path.set_cache_dir('/short/path')`.

Upgrade

Version history

1.8.10latest on PyPI · released Mar 20, 2026

Audit

Dependencies

boto3optionalRequired for accessing resources from AWS S3 (s3:// scheme).

google-cloud-storageoptionalRequired for accessing resources from Google Cloud Storage (gs:// scheme).

huggingface-huboptionalRequired for accessing resources from HuggingFace Hub (hf:// scheme).

beaker-pyoptionalRequired for accessing resources from Beaker (beaker:// scheme).

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/allenai/cached_path ↗

packagehttps://pypi.org/project/cached-path/ ↗

docshttps://cached-path.readthedocs.io/ ↗

changeloghttps://github.com/allenai/cached_path/blob/main/CHANGELOG.md ↗