Skip to content
Tutorials Center
My learning

Topics

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.

Python
from functools import cache

@cache
def square(n):
    return n * n

Try it

Python Memoizing a recursive function

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.

Python Bounded caches and the argument rules

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

Python
@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.
  • cache never forgets, which can leak memory in long-running programs. Prefer lru_cache(maxsize=...) when inputs are unbounded.
  • Keyword order matters: f(a=1, b=2) and f(b=2, a=1) may be cached as separate entries; so may f(1) and f(n=1).
  • Exceptions are not cached; the function runs again on the next call.
  • Methods: decorating a method includes self in the key, which keeps every instance alive. Cache module-level helpers, or use cached_property for per-instance values.
  • Recursion depth is still limited. A memoized fib(5000) can hit RecursionError; 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.