Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Using Python cachetools: TTLCache, LRUCache, and the cached Decorator

How to use cachetools in Python: TTLCache for time-based expiration, LRUCache for size-based eviction, and the cached decorator for wrapping functions.

~5 min readPython
#cachetools#caching#Python#decorators
Illustration of a Python cache with a clock and a gauge, representing TTLCache time expiration and LRUCache size limits.

When a Python function performs expensive work—database queries, API calls, or heavy computation—repeating that work for identical inputs wastes time and resources. cachetools provides ready-made cache classes and a cached decorator, so you can add caching with minimal code. This article covers the two most common cache types, TTLCache and LRUCache, and how to connect them to functions with the cached decorator.

Installing cachetools and basic usage

cachetools is a third-party library, so install it with pip:

bash
pip install cachetools

The library provides several cache classes, all implementing a common dictionary-like interface. The two you will use most often are TTLCache and LRUCache. You can use them directly as dictionary-like objects:

python
from cachetools import TTLCache, LRUCache # A cache that holds up to 100 items, each valid for 300 seconds ttl_cache = TTLCache(maxsize=100, ttl=300) # A cache that holds up to 100 items, evicting least recently used ones lru_cache = LRUCache(maxsize=100) # Both support standard dict operations ttl_cache['key'] = 'value' print(ttl_cache['key']) # 'value'

These classes are not just simple dictionaries—they enforce size limits and expiration policies automatically. When you insert beyond maxsize, the cache evicts items according to its policy. For TTLCache, items expire after ttl seconds; for LRUCache, the least recently accessed item is removed.

The cached decorator for function results

Instead of managing cache objects manually, cachetools provides a cached decorator that wraps a function and stores its return values. The decorator accepts a cache instance as its first argument:

python
from cachetools import cached, TTLCache cache = TTLCache(maxsize=128, ttl=600) @cached(cache) def get_user(user_id): # Simulate a slow database lookup print(f'Fetching user {user_id} from database') return {'id': user_id, 'name': 'Alice'} print(get_user(1)) # Fetches and caches print(get_user(1)) # Returns from cache, no print output

The decorator uses the function arguments to build a cache key. By default, it builds a key from the positional and keyword arguments. This works well for immutable arguments like strings, numbers, and tuples. If your function accepts mutable objects like lists or dicts, you need to provide a custom key function, as shown later.

TTLCache: time-based expiration

TTLCache is ideal when cached data becomes stale after a fixed period. Each entry stores an expiration timestamp based on the ttl value you provide. When you access an expired item, cachetools treats it as missing; cache[key] raises KeyError, while cache.get(key) returns None. The cached decorator then recomputes the function result and stores it again.

python
from cachetools import cached, TTLCache import time cache = TTLCache(maxsize=10, ttl=2) @cached(cache) def get_temperature(city): return 22.5 # Simulated API call print(get_temperature('Berlin')) # 22.5 time.sleep(3) print(get_temperature('Berlin')) # Recomputes because entry expired

TTLCache also supports per-item TTL override via the ttl parameter in the __setitem__ method, but the cached decorator uses the cache default ttl. If you need different expiration times for different calls, use a custom cache or separate decorator.

LRUCache: size-based eviction

LRUCache keeps the most recently used items and discards the least recently used when the cache reaches maxsize. This is useful when you want to bound memory usage and recency of access correlates with future usefulness. Unlike TTLCache, items never expire by time; they stay until evicted by size.

python
from cachetools import cached, LRUCache cache = LRUCache(maxsize=3) @cached(cache) def compute(n): print(f'Computing {n}') return n * n compute(1) # Computes compute(2) # Computes compute(3) # Computes compute(1) # Returns from cache (1 is most recent now) compute(4) # Computes; evicts 2 (least recently used)

After inserting 1, 2, 3, the cache holds all three. Accessing 1 makes it the most recent. Adding 4 exceeds maxsize, so the least recently used item (2) is evicted.

Comparing TTLCache and LRUCache

The choice between these two caches depends on the nature of your data and access patterns. The table below summarizes the key differences:

CriterionTTLCacheLRUCache
Eviction triggerTime since insertionCache size
ExpirationYes, after ttl secondsNo, items remain until evicted
Bound by maxsizeYesYes
Best forData that becomes stale quicklyData that stays valid and is reused frequently
Access patternAny pattern needing time-based expiryRecency-based reuse

Use TTLCache when the underlying data changes over time—for example, a weather forecast or a session token. Use LRUCache when the data is immutable and you want to avoid recomputation for frequently repeated inputs, like a memoized Fibonacci function or configuration lookups.

Practical considerations: thread safety and memory

cachetools cache classes are not thread-safe by default. If multiple threads access the same cache concurrently, the cache operations need external synchronization. The cached decorator does not add locking by default, so expose the cached function through a wrapper that holds a lock:

python
import threading from cachetools import cached, TTLCache cache = TTLCache(maxsize=100, ttl=60) lock = threading.RLock() @cached(cache) def get_data_cached(key): # Simulate expensive operation return key * 2 def get_data(key): with lock: return get_data_cached(key)

The lock serializes cache lookups, writes, and function calls through get_data. For high-concurrency scenarios, serializing all calls can become a bottleneck. Consider partitioning caches by key or using an external cache instead.

Memory usage is another concern. TTLCache and LRUCache hold references to keys and values, so large cached objects can consume significant memory. maxsize limits the number of entries by default, not the total memory footprint. If you want to bound the cache by total size, pass getsizeof to the cache constructor; both TTLCache and LRUCache accept this option. The callable is used to estimate the size of each value, and those estimates count toward maxsize.

Custom cache keys and advanced usage

The cached decorator builds a key from the function arguments using a default key function. For functions that accept mutable arguments like lists or dictionaries, the default key generation raises a TypeError because lists and dictionaries are unhashable. You can supply a custom key function to the decorator:

python
from cachetools import cached, TTLCache cache = TTLCache(maxsize=100, ttl=300) @cached(cache, key=lambda *args, **kwargs: tuple(args[0])) def process_items(items): # items is a list, which is unhashable, so tuple(items) is used as the key return sum(items) print(process_items([1, 2, 3])) # Cached under the key (1, 2, 3)

The key function receives the same arguments as the decorated function and must return a hashable value. This example assumes items is passed as a positional argument; if it might be passed by keyword, adjust the key function to handle kwargs too.

Another advanced use case is to bypass the cache for specific calls. The cached decorator does not provide a direct way to skip caching, but you can achieve this by calling the underlying function directly if you store a reference to it before decoration:

python
from cachetools import cached, TTLCache cache = TTLCache(maxsize=100, ttl=60) def _expensive(x): return x * x @cached(cache) def expensive(x): return _expensive(x) # Force recomputation by calling the inner function print(_expensive(5)) # Always recomputes

This pattern is useful when you need fresh data occasionally but still want caching for the common path.

Choosing the right cache type for your function

The decision between TTLCache and LRUCache ultimately depends on your data validity and access pattern. If you know that a value is only valid for a short period, TTLCache prevents serving stale data. If your data is immutable and you want to maximize hit rate under a fixed memory budget, LRUCache is the better fit. For many real-world scenarios, a combination of both—using TTLCache with a generous maxsize and a moderate ttl—provides a good balance: it bounds the number of entries while ensuring that entries eventually expire.

When you need both time-based expiration and size-based eviction, cachetools also offers TLRUCache (time-aware LRU), which combines both policies. This can be a better choice than layering two caches manually. The cached decorator works with any cache class that implements the required interface, so you can swap cache types without changing your function code.

Finally, remember that caching adds complexity to debugging. When a function result is cached, changes to external state may not be reflected. Always consider whether caching is appropriate for the function semantics. For functions with side effects or that depend on global mutable state, caching can lead to subtle bugs. Use caching only for pure functions that return deterministic results based on their arguments.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.