Install & Compatibility
Where this runs
tested against v7.0.0.20260713 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LRUCache
✓ from cachetools-stubs import LRUCache
✗ from cachetools import LRUCache
This quickstart demonstrates basic usage of `cachetools` decorators like `@cached` with `LRUCache` and `TTLCache`. With `types-cachetools` installed, type checkers will provide static analysis for these caching patterns, helping to ensure correct usage of cache parameters and function signatures.
from cachetools import cached, LRUCache, TTLCache
import time
# Example 1: LRUCache decorator
@cached(cache=LRUCache(maxsize=2))
def expensive_function(arg):
print(f"Calculating expensive_function({arg})")
time.sleep(0.1) # Simulate work
return arg * 2
print("--- LRUCache Example ---")
print(expensive_function(1)) # Calculates
print(expensive_function(2)) # Calculates
print(expensive_function(1)) # Cache hit
print(expensive_function(3)) # Calculates, evicts 2
print(expensive_function(2)) # Calculates again
# Example 2: TTLCache decorator
@cached(cache=TTLCache(maxsize=1, ttl=0.5))
def time_sensitive_data(key):
print(f"Fetching time_sensitive_data({key})")
return f"Data for {key} @ {time.time():.2f}"
print("\n--- TTLCache Example ---")
print(time_sensitive_data("report")) # Calculates
print(time_sensitive_data("report")) # Cache hit
time.sleep(0.6) # Wait for cache to expire
print(time_sensitive_data("report")) # Calculates again
Debug
Known issues
breakingBreaking change in `cachetools` v5.0.0: Deprecated submodules like `cachetools.ttl` were removed. Imports must now be directly from the top-level `cachetools` package (e.g., `from cachetools import TTLCache`).fixUpdate import statements: change `from cachetools.submodule import Symbol` to `from cachetools import Symbol`.
affects: cachetools >= 5.0.0
breakingBreaking change in `cachetools` v5.0.0: The `key` function passed to the `@cachedmethod` decorator now receives `self` as its first positional argument. Custom `key` functions must be updated to accept this argument.fixAdjust custom `key` functions for `@cachedmethod` to accept `self` (e.g., `def my_key_func(self, *args, **kwargs): ...`). The default key function correctly ignores `self`.
affects: cachetools >= 5.0.0
gotchaType checking `TTLCache` with `datetime.now` as `timer` and `datetime.timedelta` for `ttl` might lead to MyPy errors because `types-cachetools` (historically) often expected `float` for `ttl` if the `timer` returns a `float` (like `time.monotonic`). While `cachetools` supports `datetime.datetime` for `timer`, the stubs might not perfectly align without explicit casting or type ignores.fixConsider using `time.monotonic` for `timer` and `float` for `ttl` for simpler typing. If using `datetime.now`, ensure your type checker configuration is robust or use `typing.cast` / `# type: ignore` as a last resort until stubs are updated to fully support `datetime` types for `TTLCache`'s timer/ttl arguments.
affects: types-cachetools <= 6.2.x, cachetools >= 5.x
breakingBreaking change in `cachetools` v6.0.0: The `MRUCache` class and its corresponding `@func.mru_cache` decorator were removed.fixMigrate away from `MRUCache` to an alternative caching strategy like `LRUCache` or `FIFOCache`.
affects: cachetools >= 6.0.0
breakingBreaking change in `cachetools` v7.0.0: Dropped support for passing `info` as a fourth positional parameter to the `@cached` decorator. The `info` argument should now be accessed as `cache.info()` directly.fixRemove the `info` positional parameter from `@cached` decorator calls and retrieve cache statistics via `cache.info()`.
affects: cachetools >= 7.0.0
breakingBreaking change in `cachetools` v7.0.0: Dropped support for `cache(self)` returning `None` with `@cachedmethod` to suppress caching. Cache suppression should be handled through other means or by modifying the cache itself.fixReview and refactor code that relies on `cache(self)` returning `None` in `@cachedmethod` to disable caching. Implement explicit logic to manage cache entries instead.
affects: cachetools >= 7.0.0
gotchaThe `types-cachetools` version 6.2.0.20260317 explicitly states it targets `cachetools==6.2.*`. However, the current `cachetools` release is 7.0.5. Using `types-cachetools` 6.2.x with `cachetools` 7.x may lead to type checking inconsistencies, missing annotations for new `cachetools` 7.x features, or incorrect types for changed APIs.fixBe aware of potential type mismatches. If encountering type errors, temporarily pin `cachetools` to `~=6.2.0` or wait for `types-cachetools` to release stubs compatible with `cachetools` 7.x. Alternatively, use `# type: ignore` sparingly for known incompatibilities.
affects: types-cachetools 6.2.x, cachetools 7.x
Upgrade
Version history
7.0.0.20260713latest on PyPI · released Jul 13, 2026
Audit
Dependencies
cachetoolsrequiredProvides the runtime functionality for which these stubs are generated. This stub package is intended for cachetools==6.2.*.
pythonrequiredRequired runtime version for the stub package itself.