Python Reference ยท Standard Library: Data Structures and Functional Tools
functools.cache and lru_cache
Reference for functools.cache and lru_cache: memoize pure functions, maxsize, typed, cache_info(), cache_clear(), hashable arguments and when not to cache.
functools.cache and functools.lru_cache are decorators that remember a function's results. When the function is called again with the same arguments, the stored result is returned without running the body.
cache (3.9+) is unbounded; lru_cache can limit its size and throws away the least recently used entry when full. Both are ideal for pure functions with repeating inputs, such as recursive definitions.
from functools import cache @cache def square(n): return n * n
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Syntax
@cache def func(...): ... @lru_cache(maxsize=128, typed=False) def func(...): ...
| Name | Description |
|---|---|
maxsize |
Maximum number of stored results. None means unlimited; 0 disables caching. Default is 128. |
typed |
If True, arguments that compare equal but have different types (1 and 1.0) are cached separately. |
| Attribute | Description |
|---|---|
cache_info() |
Named tuple (hits, misses, maxsize, currsize). |
cache_clear() |
Empties the cache and resets the statistics. |
cache_parameters() |
Dict with maxsize and typed (3.9+). |
__wrapped__ |
The original, uncached function. |
Return value: the decorated function returns whatever the original returns (the same stored object each time). Raises: TypeError if an argument is unhashable.
Usage notes
- Arguments must be hashable. Lists, dicts and sets raise
TypeError; pass tuples or frozensets, or convert inside a wrapper. - Only cache pure functions. If the result depends on time, files, randomness or global state, the cache will serve stale answers.
- Cached objects are shared. A function that returns a list gives every caller the same list, so mutating it changes later results.
cachenever forgets, which can leak memory in long-running programs. Preferlru_cache(maxsize=...)when inputs are unbounded.- Keyword order matters:
f(a=1, b=2)andf(b=2, a=1)may be cached as separate entries; so mayf(1)andf(n=1). - Exceptions are not cached; the function runs again on the next call.
- Methods: decorating a method includes
selfin the key, which keeps every instance alive. Cache module-level helpers, or usecached_propertyfor per-instance values. - Recursion depth is still limited. A memoized
fib(5000)can hitRecursionError; warm it with smaller values first or iterate. - Thread safety: the cache structure is safe, but the function may run twice if two threads miss at once.