---
id: shelved-cache
version: "0.5.0"
license: MIT
license_treatment: permissive
maintenance: aging
---

# shelved-cache — Persistent cache for Python cachetools.

License: permissive · Maintenance: aging · Downloads: 4.8M/mo

## What it is and what it does

shelved-cache adds disk persistence to cachetools cache objects, allowing you to wrap any cachetools cache (LRU, TTL, etc.) so that cached entries are automatically written to a file and survive program restarts. You create a PersistentCache instance around a cachetools cache class, then use it exactly like the underlying cache—reading and writing entries works the same way, but data persists to disk via Python's shelve module.

The package also provides async-aware decorators (cachedasyncmethod, cachedfunction) that work with both synchronous and asynchronous functions, and a utility function (autotuple_hashkey) to make list arguments hashable for caching. It's a thin layer on top of cachetools, designed for applications that need simple file-backed caching without external dependencies like Redis.

Use it for:

- Cache expensive function results across program runs without setting up a database or external cache service.
- Decorate async methods with persistent caching using the async decorator support.
- Build a simple memoization layer for CLI tools or batch scripts that benefit from remembering past computations.
- Persist LRU or TTL cache state to disk for recovery after crashes or restarts.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Wraps cachetools cache implementations with disk persistence, allowing cached data to survive across program restarts while maintaining the same cache interface.

Yes, if you need simple disk-backed caching and don't want external dependencies. The low install friction, permissive license, and straightforward API make it a reasonable choice for small to medium projects. However, be aware that the package is aging (last release 242 days ago) and has a known issue on Windows with Python 3.13+; verify that issue doesn't affect your platform before committing to it for production use.

## Install

pip install shelved-cache
uv add shelved-cache
poetry add shelved-cache

## Installing shelved-cache

Before you install: Low friction install with a single runtime dependency (cachetools). Maintenance status is aging—last release was 242 days ago—but the repository remains active and the package supports current Python versions through 3.14.

License in practice: MIT license is permissive; you can use this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install shelved-cache

from shelved_cache import PersistentCache
from cachetools import LRUCache

pc = PersistentCache(LRUCache, filename='mycache', maxsize=2)
pc["key"] = 42
print(pc["key"])  # 42
pc.close()

Requires Python 3.10 or later. Known permission errors reported on Windows with Python 3.13 and above.

Verify before relying:

- Whether the Windows permission issue on Python 3.13+ affects your use case or has been resolved in practice.
- Performance characteristics when cache files grow large or are accessed frequently across multiple processes.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 4.8M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

persistent disk cache python, cachetools disk storage, cache to file python, persistent lru cache, cache serialization disk, caching, persistence, file-backed

[View on SkillFed](https://skillfed.io/packages/shelved-cache) · [View on PyPI](https://pypi.org/project/shelved-cache/)