Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 38 ยท State and Caching

Caching with cache_data and cache_resource

Speed up Streamlit apps with st.cache_data and st.cache_resource. Learn cache keys, ttl, max_entries, hashing rules, clearing caches and common pitfalls.

Because every interaction reruns your script, anything slow at the top of the file is paid for again and again: reading a big CSV, calling an API, running a SQL query, loading a machine-learning model. Caching stores the result of a function the first time it runs and returns the stored result on later calls with the same arguments. Streamlit has two decorators for this, and choosing the right one is most of the skill.

The two decorators

@st.cache_data @st.cache_resource
For Data: DataFrames, lists, dicts, numbers, strings, arrays Shared objects: ML models, database connections, clients
What is stored A copy of the returned value for each call The same object, shared by every call and every user
Return value is Pickled; each caller gets a fresh copy, so mutating it is safe Not copied; mutating it changes it for everyone
Needs picklable result Yes No
Typical lifetime Until ttl expires or cache cleared Until the server restarts or cache cleared

A good rule: if it is a value (something you would save to a file), use cache_data. If it is a thing (an object with state, a connection, a model), use cache_resource.

Python
import pandas as pd
import streamlit as st

@st.cache_data
def load_sales(path):
    return pd.read_csv(path)          # slow work happens once per distinct path

@st.cache_resource
def load_model():
    import joblib
    return joblib.load("model.joblib") # one model object shared by all sessions

sales = load_sales("sales.csv")
model = load_model()

On the first call with a given path, the function body runs and Streamlit stores the result. On the next rerun (and for every other user) with the same path, the body is skipped and the stored value is returned.

How the cache key works

The cache key is built from the function's source code and the values of its arguments. If either changes, the old entry is not used. Streamlit hashes the arguments, so arguments must be hashable by Streamlit's hasher (strings, numbers, lists, dicts, DataFrames, NumPy arrays and many other types work).

The stand-in below builds this idea in plain Python, with timing counters instead of real waiting. Notice that the same arguments give a hit and different arguments give a miss.

Python Stand-in: memoization with a call counter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Five calls, two real executions: that is the whole idea.

Copies versus shared objects

cache_data returns a copy each time. This protects the cache: if your code does df["new"] = 1 on the returned DataFrame, the cached original is untouched and the next caller still receives the clean version. That safety costs a copy for large data.

cache_resource returns the very same object. That is exactly what you want for a model or a connection (you do not want 50 copies of a 500 MB model) but means you must treat it as shared state. Do not store per-user data inside it, and make sure it is safe to use from several threads, because two sessions may use it at once.

The difference matters in practice, so try it:

Python Stand-in: copy versus shared object

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The data copy stays [1, 2, 3], while the shared resource now contains 99 for everyone. That is why connections and models go in cache_resource, and results go in cache_data.

Expiry: ttl and max_entries

Cached data can get stale. Two parameters control it, on both decorators:

Python
@st.cache_data(ttl=600)                 # drop entries older than 10 minutes
def fetch_prices():
    ...

@st.cache_data(ttl="1h", max_entries=50)  # keep at most 50 argument combinations
def search(query):
    ...
  • ttl (time to live) accepts seconds or a string like "30m", "1d", or a timedelta. After it expires the next call recomputes.
  • max_entries caps how many distinct argument combinations are stored. The least recently used are removed first. Always set it when arguments come from user input (a search box), otherwise memory grows without bound.
  • show_spinner="Loading data..." shows custom text while a cache miss computes; show_spinner=False hides it.

The stand-in below adds a ttl using a fake clock so the result is deterministic.

Python Stand-in: ttl expiry with a fake clock

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

At 0 s it computes, at 30 s and 59 s it hits, at 61 s the entry has expired so it computes again, and at 90 s it hits the new entry.

Clearing caches

Python
load_sales.clear()                      # clear one function's cache
st.cache_data.clear()                   # clear every cache_data function
st.cache_resource.clear()               # clear every cache_resource function

A common pattern is a "Refresh data" button that calls .clear() and then st.rerun(). Also, editing the source of a cached function automatically invalidates it, because the code is part of the key.

Things that cannot be hashed

If an argument is something Streamlit cannot hash (a database connection, a file handle, a lambda), it raises UnhashableParamError. Two fixes:

  • Prefix the parameter with an underscore: def query(_conn, sql):. Streamlit then ignores that parameter in the key. Use it for connections and models passed in, while the meaningful arguments still form the key.
  • Provide hash_funcs to teach Streamlit how to hash a custom type.
Python
@st.cache_data
def run_query(_conn, sql):             # only sql is part of the cache key
    return pd.read_sql(sql, _conn)

Caching and side effects

A cached function body is skipped on a hit, so anything it does besides returning a value (printing, writing files, drawing with st.write) happens only on misses. Streamlit does replay some st. elements drawn inside a cached function, with a warning in the docs about widgets inside cached functions. Keep cached functions pure: given the same arguments, they should return the same thing, and not draw widgets. Do the drawing outside.

Cache or session state?

Question Use
Is it expensive to compute and the same for many users? cache_data / cache_resource
Is it one user's choices or progress? st.session_state
Must it survive a server restart? A database or file

A cache is shared across sessions and is only an optimization. It can disappear at any time (a restart, expiry, eviction), so your code must always work on a miss.

Common mistakes

  • Caching a function that reads user-specific data without making the user part of the arguments, so one user sees another's result.
  • Using cache_resource for DataFrames, then mutating them.
  • Forgetting ttl on data that changes (prices, live databases).
  • Putting widgets or st.write calls inside cached functions.
  • Passing a connection as a normal argument instead of _conn.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which decorator is right for a loaded machine-learning model shared by all users?

    Models are objects that should exist once and be shared. cache_resource returns the same object without copying it.
  2. 2. What does cache_data return on a cache hit?

    cache_data returns a fresh copy, so mutating the result cannot corrupt the cache.
  3. 3. What does a leading underscore in a parameter name (_conn) do in a cached function?

    Underscored parameters are skipped when building the key. It is the usual way to pass connections or other unhashable objects.
  4. 4. A search box passes free text into a cached function. Which setting protects memory?

    Every distinct query creates a new entry. max_entries evicts the least recently used ones so memory stays bounded.

Summary

  • @st.cache_data stores copies of returned values; @st.cache_resource shares one object across all sessions.
  • The key is the function source plus argument values; change either and the cache misses.
  • Use ttl for stale data and max_entries for user-driven arguments.
  • Clear with func.clear(), st.cache_data.clear() or st.cache_resource.clear().
  • Prefix unhashable parameters with _ to leave them out of the key.
  • Keep cached functions pure and always be ready for a miss.

Next: Files, CSV and Excel