Skip to content

Python functools.lru_cache: memoize calls (3.2+)

  • What @lru_cache stores, how it builds cache keys and how least-recently-used eviction works.
  • The API: maxsize, typed, cache_info(), cache_clear(), cache_parameters() and __wrapped__, plus the simpler @cache.
  • How to raise the hit rate by normalizing arguments, and how to add time-based expiry.
  • The traps: shared mutable results, methods that keep instances alive, impure functions and keyword-order misses.
  • When to choose lru_cache, cache, cached_property or an external cache.

functools.lru_cache is a decorator that wraps a function with a memoizing callable: it remembers the result for each distinct set of arguments and returns the stored result on the next identical call instead of running the function again. With a numeric maxsize (default 128), the least recently used entry is evicted when the cache is full; with maxsize=None the cache grows without limit. functools.cache, added in Python 3.9, is the same as lru_cache(maxsize=None) but smaller and faster. lru_cache has been in the standard library since Python 3.2 and is fully current in Python 3.14.

Some functions are pure but expensive: they always return the same result for the same input, yet each call costs a network round trip, a file read or heavy computation. In OrdersPortal, looking up a VAT rate means asking a slow configuration service, and checkout asks for the same few countries thousands of times an hour. A hand-written dictionary cache works, but it never evicts, gives no statistics and is easy to get subtly wrong.

Running the samples: each sample is a complete script. Save it as a .py file and run it with Python 3.14 (python3 sample.py). Outputs were produced with CPython 3.14.6; samples using @cache need Python 3.9 or later.

import time
from functools import lru_cache
CALLS = 0
def tax_rate_uncached(country: str) -> float:
global CALLS
CALLS += 1
time.sleep(0.05) # stands in for a slow config service
return {"DE": 0.19, "FR": 0.20, "NL": 0.21}[country]
# Before: a hand-written cache that never evicts and is easy to get wrong.
_rates: dict[str, float] = {}
def tax_rate_manual(country: str) -> float:
if country not in _rates:
_rates[country] = tax_rate_uncached(country)
return _rates[country]
# After: one decorator, bounded, with statistics.
@lru_cache(maxsize=64)
def tax_rate(country: str) -> float:
return tax_rate_uncached(country)
for country in ["DE", "FR", "DE", "DE", "NL", "FR"] * 50: # 300 lookups
tax_rate(country)
print(CALLS, "slow calls")
print(tax_rate.cache_info())

Output:

3 slow calls
CacheInfo(hits=297, misses=3, maxsize=64, currsize=3)

Three hundred lookups cost three slow calls. cache_info() reports the evidence you need to tune the cache: hits, misses, the configured maxsize and the current number of entries.

lru_cache can be used bare (@lru_cache, since Python 3.8) or with arguments (@lru_cache(maxsize=128, typed=False)). Internally it is a dictionary keyed on the call’s arguments, plus bookkeeping that tracks recency so the oldest entry can be evicted.

from functools import cache, lru_cache
@lru_cache(maxsize=2)
def price(sku, qty=1):
print(f" computing {sku} x{qty}")
return qty * 10
price("MUG-01"); price("PEN-02"); price("MUG-01") # MUG-01 is now most recent
price("CAP-07") # evicts PEN-02, the least recent
price("PEN-02") # recomputed
print(price.cache_info())
# Keys follow the call shape, not the meaning.
price.cache_clear()
price("MUG-01", 2); price("MUG-01", qty=2); price(qty=2, sku="MUG-01")
print(price.cache_info())
# typed=True separates 3 and 3.0.
@lru_cache(typed=True)
def half(n):
return n / 2
half(3); half(3.0)
print(half.cache_info(), half.cache_parameters())
# Arguments must be hashable.
try:
price(["MUG-01"])
except TypeError as exc:
print("TypeError:", exc)
# @cache is lru_cache(maxsize=None); __wrapped__ bypasses the cache.
@cache
def fib(n):
return n if n < 2 else fib(n - 1) + fib(n - 2)
print(fib(80), fib.cache_info())
print(fib.__wrapped__(10))

Output:

computing MUG-01 x1
computing PEN-02 x1
computing CAP-07 x1
computing PEN-02 x1
CacheInfo(hits=1, misses=4, maxsize=2, currsize=2)
computing MUG-01 x2
computing MUG-01 x2
computing MUG-01 x2
CacheInfo(hits=0, misses=3, maxsize=2, currsize=2)
CacheInfo(hits=0, misses=2, maxsize=128, currsize=2) {'maxsize': 128, 'typed': True}
TypeError: unhashable type: 'list'
23416728348467685 CacheInfo(hits=78, misses=81, maxsize=None, currsize=81)
55

What the output shows:

  • LRU eviction. A hit moves the entry to “most recent”. When a new result arrives and the cache is full, the least recently used entry goes, not the oldest inserted. PEN-02 was evicted because MUG-01 had been touched more recently.
  • Keys are built from the call as written. The documentation warns that distinct argument patterns may be cached separately. price("MUG-01", 2), price("MUG-01", qty=2) and price(qty=2, sku="MUG-01") are three misses for one logical call. Defaults are not filled in either.
  • typed=True stores 3 and 3.0 separately. With the default typed=False, equal values of different types usually share one entry, because 3 == 3.0 and they hash the same.
  • Hashable arguments only. Lists, dicts and sets raise TypeError. Pass tuples or frozensets instead.
  • Recursion. Because the recursive call goes through the decorated name, fib(80) computes each value once: 81 misses instead of billions of calls.
  • Helpers. cache_clear() empties the cache, cache_parameters() (3.9) reports maxsize and typed, and __wrapped__ is the original function for tests or bypassing the cache.

The cache holds strong references to every argument and result until they are evicted or cleared. It is thread-safe in the sense that its internal structure stays coherent, but the documentation notes that two threads can both miss and both run the function before either result is stored.

OrdersPortal shows shipping quotes on every product page. Rates depend only on a shipping zone and a weight band, the carrier’s rate service is slow, and the carrier publishes new rates a few times a day. The example normalizes inputs before they reach the cache, returns immutable results, adds a five-minute expiry and supports clearing on demand.

import time
from dataclasses import dataclass
from decimal import Decimal
from functools import lru_cache
@dataclass(frozen=True)
class Quote:
carrier: str
price: Decimal
days: int
RATE_TABLE_CALLS = 0
def _load_rates(zone: str) -> dict[str, tuple[Decimal, int]]:
"""Stands in for a slow call to the carrier rate service."""
global RATE_TABLE_CALLS
RATE_TABLE_CALLS += 1
base = {"EU-1": Decimal("4.90"), "EU-2": Decimal("7.50")}[zone]
return {"standard": (base, 3), "express": (base * 2, 1)}
def _ttl_bucket(seconds: int = 300) -> int:
"""Changes value every `seconds`, so cache entries expire with it."""
return int(time.monotonic() // seconds)
@lru_cache(maxsize=512)
def _cached_quotes(zone: str, weight_band: int, _bucket: int) -> tuple[Quote, ...]:
rates = _load_rates(zone)
return tuple(
Quote(name, price + Decimal("1.25") * weight_band, days)
for name, (price, days) in rates.items()
)
def shipping_quotes(postcode: str, weight_kg: float) -> tuple[Quote, ...]:
# Normalize BEFORE the cache: "10115 " and "10117" share zone EU-1,
# and 1.2 kg and 1.9 kg share weight band 1. More hits, smaller cache.
zone = "EU-1" if postcode.strip().startswith("1") else "EU-2"
weight_band = int(weight_kg)
return _cached_quotes(zone, weight_band, _ttl_bucket())
for postcode, kg in [("10115 ", 1.2), ("10117", 1.9), ("80331", 0.4), ("10115", 1.5)]:
best = min(shipping_quotes(postcode, kg), key=lambda q: q.price)
print(postcode.strip(), kg, best.carrier, best.price)
print(_cached_quotes.cache_info(), "rate service calls:", RATE_TABLE_CALLS)
# Results are immutable, so no caller can corrupt the shared cached value.
try:
shipping_quotes("10115", 1.0)[0].price = Decimal("0")
except AttributeError as exc:
print(type(exc).__name__, exc)
# When the carrier publishes new rates, drop everything at once.
_cached_quotes.cache_clear()
print(_cached_quotes.cache_info())

Output:

10115 1.2 standard 6.15
10117 1.9 standard 6.15
80331 0.4 standard 7.50
10115 1.5 standard 6.15
CacheInfo(hits=2, misses=2, maxsize=512, currsize=2) rate service calls: 2
FrozenInstanceError cannot assign to field 'price'
CacheInfo(hits=0, misses=0, maxsize=512, currsize=0)

Four requests become two cache entries because the public function reduces raw input (postcodes, exact weights) to the few values that actually determine the answer. The cached function is private, so callers cannot bypass normalization. The _bucket argument gives approximate expiry: when the bucket number changes, new calls miss and fetch fresh rates. Entries from the old bucket are not deleted; they simply stop being used and age out through LRU eviction, which is why maxsize stays bounded. Returning a tuple of frozen dataclasses means every caller shares the same cached objects safely.

import gc
import weakref
from functools import lru_cache
# 1. A cached mutable result is shared by every caller.
@lru_cache
def default_tags(channel):
return ["new"]
tags = default_tags("web")
tags.append("vip") # mutates the cached list
print(default_tags("web"))
# 2. Caching a method keeps every instance alive.
class Order:
def __init__(self, order_id):
self.order_id = order_id
@lru_cache(maxsize=128)
def summary(self):
return f"Order {self.order_id}"
order = Order("ORD-1")
order.summary()
ref = weakref.ref(order)
del order
gc.collect()
print("still alive:", ref() is not None, Order.summary.cache_info().currsize)
# 3. Caching an impure function freezes its first answer.
import random
@lru_cache
def discount_code():
return f"SAVE-{random.randint(1000, 9999)}"
print(discount_code() == discount_code())

Output:

['new', 'vip']
still alive: True 1
True
  • Returning mutable objects. Every caller receives the same cached object, so one caller’s append changes what everyone else sees. Return tuples, frozensets or frozen dataclasses, or copy on the way out.
  • Decorating methods. self is part of the key, so the cache, shared by all instances at class level, keeps every instance alive until it is evicted. Use functools.cached_property for argument-free values, or build a per-instance cache in __init__ (self.summary = lru_cache(maxsize=32)(self._summary)).
  • Caching impure or side-effecting functions. The documentation is explicit: caching makes no sense for time(), random(), functions with side effects, or functions that must return distinct mutable objects such as generators and coroutines.
  • Unbounded caches on unbounded inputs. @cache keyed on order IDs or user input is a memory leak in a long-running server. Use a numeric maxsize and watch currsize.
  • Forgetting to invalidate. Results stay until evicted or cleared. Call cache_clear() when the underlying data changes, and in test fixtures so tests do not leak state into each other.
  • Inconsistent call shapes. Mixing positional and keyword calls splits the cache. Wrap the cached function in one that always calls it the same way, as the realistic example does.

Use lru_cache for pure, deterministic functions with hashable arguments, where the same inputs recur and each call is expensive. Do not use it for values that must be fresh, for data shared across processes or servers, or when correctness depends on seeing updates immediately.

Need Best tool
Pure function, small finite input space @functools.cache (3.9+)
Pure function, open-ended inputs, long-running process @lru_cache(maxsize=N)
Expensive attribute computed once per object @functools.cached_property (3.8+)
Expiry after a fixed time lru_cache plus a time-bucket argument, or a dedicated TTL cache library
Shared across processes or servers, or must survive restarts An external cache such as Redis or memcached
Async functions An async-aware cache; lru_cache would cache a coroutine object that can be awaited only once
Version Change
3.2 functools.lru_cache added.
3.3 typed parameter added.
3.8 Bare @lru_cache without parentheses (the user_function form); functools.cached_property added.
3.9 functools.cache and cache_parameters() added.
3.14 Current release; no changes to lru_cache itself.

1. What happens on a call to a full lru_cache(maxsize=128) with new arguments? The function runs, its result is stored, and the least recently used entry is evicted so the cache stays at 128 entries. “Used” includes hits, so frequently requested entries stay in the cache even if they were inserted long ago.

2. Why might f(1, b=2) and f(1, 2) both be cache misses after one of them was already called? The key is built from the positional and keyword arguments as passed, not from the bound parameters. Different call shapes, including different keyword order, can produce different keys. Normalize calls through a wrapper if hit rate matters.

3. Why is decorating an instance method with @lru_cache discouraged? The cache lives on the function, which is shared by the class, and self is part of each key. Every instance used as a key is kept alive until evicted or cleared, which can cause memory growth, and results for different instances compete for the same maxsize. Prefer cached_property or a per-instance cache.

4. Senior scenario: after adding @lru_cache(maxsize=None) to OrdersPortal’s get_customer_profile(customer_id), memory grows steadily and support reports stale addresses. What went wrong and what do you do? Two problems: the cache is unbounded and keyed on an open-ended ID, so it grows with every customer seen, and profiles are mutable data with no invalidation, so updates never appear. An in-process lru_cache is the wrong layer here. Remove it or bound it tightly with a short time bucket, invalidate on profile updates, and measure hit rate with cache_info(). If profile reads are genuinely a bottleneck across several workers, use a shared cache with explicit TTLs and invalidation on write, so every process sees the same data.

  • @lru_cache memoizes by argument values; maxsize (default 128) bounds it with least-recently-used eviction.
  • @cache (3.9) is the unbounded, faster form for small, finite input spaces.
  • Arguments must be hashable, call shape affects the key, and results are shared, so return immutable values.
  • Avoid it on instance methods, impure functions and data that must be fresh; clear it when the source changes.
  • Use cache_info() to prove the cache helps before keeping it.