st.cache_data vs st.experimental_memo: Choosing the Right Decorator for Repeatable Data Loading

Direct answer for your CSV reload goal

Use @st.cache_data. In Streamlit 1.18+ it is the stable API for data loading and it is the documented replacement for st.experimental_memo. Both decorators will return the same cached result across script restarts when the inputs are identical, but st.cache_data gives you a stable contract and a serialized copy of the return value. st.experimental_memo is legacy and is subject to removal or behavior changes in future releases.

Confirmed facts

• st.cache_data is the stable replacement for st.experimental_memo and is recommended for data-loading tasks.
• st.cache_data stores a serialized copy of the return value, so mutations to the returned object do not affect the cached value.
• st.experimental_memo was the precursor to st.cache_data; in 1.18+ it is functionally redundant and considered legacy.
• Both decorators rely on hashing input arguments to decide cache hits. If the input, e.g., a file path string, stays the same, the cache is hit.
• Caching does not automatically track external file changes. You must pass a value that changes when the file changes, such as modification time or content hash, as an argument.

Likely explanation vs uncertainty

Likely: st.experimental_memo may invalidate unexpectedly after upgrades because its API is experimental. Confirmed: the stable API is st.cache_data. Handling of unhashable inputs is similar for both: Streamlit attempts to hash arguments. Passing large unhashable objects like a DataFrame with a mutable index as an argument can trigger hashing errors or high overhead. The recommended pattern is to avoid passing unhashable objects as cache keys and instead pass hashable proxies such as path strings and timestamps.

Steps needed for repeatable CSV loading with invalidation on file change

1. Decorate the loader with @st.cache_data. Do not use st.experimental_memo for new code.
2. Accept only hashable arguments: file path string and a file-change token.
3. Compute the change token outside the cached function or as a second argument, e.g., os.path.getmtime(path) or a content hash.
4. Return a pandas DataFrame. The decorator will serialize a copy.

import os
import pandas as pd
import streamlit as st

@st.cache_data
def load_csv(path: str, mtime: float):
    return pd.read_csv(path)

path = "data.csv"
mtime = os.path.getmtime(path)
df = load_csv(path, mtime)

With this pattern the cache survives a full app reload and is invalidated only when mtime changes.

Future upgrade impact

st.cache_data is stable. st.experimental_memo is subject to removal or behavior changes in newer Streamlit releases. Migrating now avoids breaking changes later.

Assumption: Streamlit 1.18 or newer, default on-disk cache enabled. If you are running with a non-persistent cache directory or an older patch, verify cache persistence in your deployment.