Introduction
Streamlit reruns your entire script on every interaction. Click a button → whole script re-executes. Without caching, a 2-second DB query runs on every click, and your app feels sluggish.
@st.cache_data and @st.cache_resource fix this: cache expensive computations and reuse them across reruns. This post explains both, when to use which, and the pitfalls that trip everyone up.
The two decorators
@st.cache_data |
@st.cache_resource |
|
|---|---|---|
| Caches | Data (DataFrames, lists, dicts, primitives) | Resources (DB connections, ML models, file handles) |
| Returns | A copy (safe to mutate) | The same object (shared) |
| Use for | load_data(), compute_metrics() |
get_db_connection(), load_model() |
| Serialization | Pickled | Not serialized (lives in memory) |
Rule of thumb: if it’s data you’ll transform → cache_data. If it’s a connection/model you’ll call methods on → cache_resource.
Step 1: Basic caching
import streamlit as st
import pandas as pd
import time
@st.cache_data
def load_data(path):
time.sleep(2) # simulate slow load
return pd.read_csv(path)
df = load_data("sales.csv") # 2s first time, instant after
st.dataframe(df)
First run: 2s. Every subsequent rerun: instant (returns cached copy).
Step 2: TTL (time-to-live)
Cache expires after N seconds — perfect for data that changes:
@st.cache_data(ttl=300) # 5 minutes
def fetch_live_prices():
return requests.get("https://api.example.com/prices").json()
After 5 minutes, the next call re-runs the function and refreshes the cache.
Step 3: cache_resource for connections
@st.cache_resource
def get_db():
import sqlite3
return sqlite3.connect("app.db", check_same_thread=False)
conn = get_db() # created once, reused forever
Never put a DB connection in cache_data — it’ll try to pickle it and fail (or worse, create a new connection each run).
Step 4: Hashing and unhashable args
Streamlit hashes the function arguments to decide cache hits. Unhashable types (DataFrames, custom objects) need a hasher:
@st.cache_data(hash_funcs={pd.DataFrame: lambda df: df.shape})
def process(df):
return df.describe()
Or use hash_funcs with a custom function. If you skip this, Streamlit throws UnhashableTypeError.
Step 5: Clearing the cache
if st.button("Refresh data"):
load_data.clear() # clear just this function
st.rerun()
# Or clear everything
st.cache_data.clear()
st.cache_resource.clear()
Step 6: Show cache status
@st.cache_data(show_spinner="Loading data...")
def load_data(path):
...
The spinner shows only on cache miss (first run). On cache hit, it’s instant with no spinner — users love this.
Step 7: Performance tips beyond caching
- Use
st.fragment(new in 1.37+) to rerun only part of the app:@st.fragment def metric_panel(): st.metric("Sales", compute_sales()) # only this reruns on interaction - Paginate large DataFrames —
st.dataframe(df.head(100))not the whole thing. - Lazy load — don’t compute until needed (inside
if st.button). - Use Polars for big data (see Pandas vs Polars).
- Avoid
st.writein loops — batch output.
Common mistakes
- Caching a function with side effects —
@st.cache_dataon a function that writes to a DB will skip the write on cache hit. Only cache pure functions. - Mutating cached data —
cache_datareturns a copy, so mutation is safe. Butcache_resourcereturns the same object — mutating it affects all users. - Forgetting
ttl— stale data is worse than slow data. Set TTL for anything time-sensitive. - Caching too much — caching a 1GB DataFrame wastes memory. Cache aggregates, not raw data.
- Hashing issues — if your function takes a DataFrame, provide a
hash_funcsor it’ll error.
Key Concepts
@st.cache_data= cache return values (data), returns copies@st.cache_resource= cache objects (connections, models), shared- TTL = auto-expire cache after N seconds
hash_funcs= tell Streamlit how to hash unhashable argsst.fragment= partial reruns for performance
What to Try Next
- Add caching to your data dashboard — measure the speedup.
- Use
st.fragmentto make only the chart panel rerun on filter changes. - Combine with Streamlit 2026 features (
st.skeletonfor the first load). - Profile with
streamlit run app.py --logger.level=debugto find slow spots.
FAQ
cache_data vs cache_resource — quick rule?
Data you’ll transform or display → cache_data. Objects you’ll call methods on (connections, models, clients) → cache_resource. When in doubt: if mutating the return value should affect other users, use cache_resource; otherwise cache_data.
Does caching work across users?
Yes — cache_data and cache_resource are shared across all users of the app (global cache). This is great for shared data but means you shouldn’t cache user-specific secrets.
How do I debug cache misses?
Set @st.cache_data(show_spinner=True) and watch the spinner. If it shows on every interaction, your args are changing (e.g., a DataFrame with different row order). Stabilize the inputs.