cachetools: Extensible Memoizing Collections and Decorators

7.0.5 verified Tue May 12 auth: no python install: verified quickstart: verified

Provides various memoizing collections and decorators, including variants of Python's @lru_cache function decorator. Current version: 7.0.5. Release cadence: Regular updates with new features and improvements.

pip install cachetools

Common errors

error ModuleNotFoundError: No module named 'cachetools' ↓

cause The 'cachetools' library has not been installed in your Python environment.

fix

Run pip install cachetools in your terminal to install the package.

error KeyError ↓

cause This often occurs in multi-threaded environments when a cache is accessed concurrently without proper synchronization, or when an item is requested after its Time-To-Live (TTL) has expired and it's been removed (or is being removed) by another thread. The base cache classes are not inherently thread-safe.

fix

When using cache decorators like @cached or @ttl_cache, provide a suitable lock object (e.g., lock=threading.Lock()) for thread-safe operations. If manually managing a cache instance, wrap access with explicit locking using threading.Lock.

error TypeError: unhashable type: 'dict' ↓

cause Cache keys or function arguments used for caching must be hashable. Python dictionaries are mutable and therefore not hashable by default, leading to this error if passed directly as a key or argument without a custom key function.

fix

Provide a custom key function to the cache decorator (e.g., @cached(cache=LRUCache(maxsize=128), key=cachetools.keys.hashkey)) to transform unhashable arguments into a hashable representation, such as a tuple of sorted items or a unique identifier.

error AttributeError: module 'cachetools' has no attribute 'func' ↓

cause This error typically indicates an attempt to access cache decorators (like `lru_cache` or `ttl_cache`) via an outdated import path (`cachetools.func`). In current versions, these decorators are generally imported directly from the `cachetools` module or used via the `cached` decorator with a cache instance.

fix

Import the specific cache decorator or class directly from the cachetools module (e.g., from cachetools import cached, LRUCache, TTLCache) and use them as @cached(cache=LRUCache(...)) or @ttl_cache(...).

error AttributeError: 'dict' object has no attribute 'append' ↓

cause This occurs when an `LRUCache` (or similar) is initialized with a `missing` function that returns a dictionary, but the user then tries to apply a list-specific method like `append` to a value retrieved from that cache, expecting a list instead of a dictionary.

fix

Ensure that the missing factory function provided to the cache returns the expected mutable type (e.g., a list missing=lambda k: [] if you intend to use list methods) or handle the returned dictionary type appropriately without calling list methods on it.

Warnings

breaking Support for cache(self) returning None to suppress any caching has been deprecated. cache(self) should always return a valid cache object. ↓

fix Ensure that the cache function always returns a valid cache object.

deprecated The typed argument in the cached decorator is deprecated. Use key=typedkey instead. ↓

fix Replace 'typed=True' with 'key=typedkey' in the cached decorator.

gotcha Access to a shared cache from multiple threads must be properly synchronized to avoid concurrency issues. ↓

fix Use a suitable lock object when accessing the cache from multiple threads.

gotcha Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead. ↓

fix Use a virtual environment for installing Python packages to avoid permission issues and conflicts with the system package manager.

gotcha The provided test output does not contain a clear error message or stack trace that can be mapped to a specific library behavior change or issue. ↓

fix Investigate the meaning of the numerical output `267914296` in the context of the executed test to determine the actual failure mode. If it represents an unexpected return value, compare it against expected behavior for the specific library/function being tested.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.01s 17.9M

3.10 slim (glibc) - - 0.01s 18M

3.11 alpine (musl) - - 0.01s 19.8M

3.11 slim (glibc) - - 0.01s 20M

3.12 alpine (musl) - - 0.01s 11.6M

3.12 slim (glibc) - - 0.01s 12M

3.13 alpine (musl) - - 0.01s 11.3M

3.13 slim (glibc) - - 0.01s 12M

3.9 alpine (musl) - - 0.01s 17.4M

3.9 slim (glibc) - - 0.00s 18M

Imports

Cache
```
from cachetools import Cache
```
Cache is the base class for all cache implementations.
LRUCache
```
from cachetools import LRUCache
```
LRUCache is a cache implementation that discards the least recently used items.
cached
```
from cachetools import cached
```
cached is a decorator for memoizing function calls.

Quickstart verified last tested: 2026-04-23

A simple example demonstrating the use of cachetools to memoize Fibonacci number calculations.

import os
from cachetools import cached, LRUCache

# Initialize a cache with a maximum size of 128
cache = LRUCache(maxsize=128)

@cached(cache)
def fib(n):
    if n < 2:
        return n
    return fib(n - 1) + fib(n - 2)

# Compute the 42nd Fibonacci number
print(fib(42))