Tech With Galvan
Back to Articles
TechJun 28, 2026 • 5 min read

Streamlit Caching & Performance: @st.cache_data and @st.cache_resource

Speed up your Streamlit apps with @st.cache_data and @st.cache_resource — when to use which, TTL, hashing, and common pitfalls.

Galvan
Galvan

Founder & Creator

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

  1. 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
  2. Paginate large DataFrames — st.dataframe(df.head(100)) not the whole thing.
  3. Lazy load — don’t compute until needed (inside if st.button).
  4. Use Polars for big data (see Pandas vs Polars).
  5. Avoid st.write in loops — batch output.

Common mistakes

  • Caching a function with side effects — @st.cache_data on a function that writes to a DB will skip the write on cache hit. Only cache pure functions.
  • Mutating cached data — cache_data returns a copy, so mutation is safe. But cache_resource returns 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_funcs or 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 args
  • st.fragment = partial reruns for performance

What to Try Next

  • Add caching to your data dashboard — measure the speedup.
  • Use st.fragment to make only the chart panel rerun on filter changes.
  • Combine with Streamlit 2026 features (st.skeleton for the first load).
  • Profile with streamlit run app.py --logger.level=debug to 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.