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.

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:
pip install cachetoolsThe 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:
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:
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 outputThe 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.
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 expiredTTLCache 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.
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:
| Criterion | TTLCache | LRUCache |
|---|---|---|
| Eviction trigger | Time since insertion | Cache size |
| Expiration | Yes, after ttl seconds | No, items remain until evicted |
Bound by maxsize | Yes | Yes |
| Best for | Data that becomes stale quickly | Data that stays valid and is reused frequently |
| Access pattern | Any pattern needing time-based expiry | Recency-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:
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:
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:
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 recomputesThis 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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.