st.session_state memory consumption during multi-user scaling

Answer

To keep the memory footprint of st.session_state under control when many users are active, store only lightweight identifiers in the session state and keep large objects (DataFrames, model weights, etc.) in shared caches or external storage, loading them on demand.

Confirmed facts

• Streamlit keeps each user’s st.session_state in the server’s RAM for the lifetime of that session.
• The state is automatically cleared when the session ends (browser close, refresh, or after server.sessionTimeout seconds of inactivity).
• There is no built‑in per‑key TTL, memory‑quota, or automatic eviction API for individual st.session_state entries.
• Streamlit’s caching decorators (@st.cache_data, @st.cache_resource) provide shared, evictable storage that is not duplicated per session.

Recommended steps

1. Store only identifiers: Put a UUID, filename, or database key in st.session_state that points to the heavy object.
2. Use shared caches: Place the large data in a function decorated with @st.cache_data (for DataFrames) or @st.cache_resource (for models). The cached object lives once per process and is reused across sessions.
3. Offload to disk or external store: If caching is not sufficient, serialize the object to a local file, SQLite, or Redis and keep only the path/key in session state. Load the data when needed and delete it after use.
4. Implement manual TTL: Save a timestamp alongside the cached entry (e.g., st.session_state['df_key'] = {'path': '...', 'ts': time.time()}). At the top of each script run, compare the timestamp to a desired TTL and delete stale entries.
5. Configure session timeout: Adjust server.sessionTimeout in .streamlit/config.toml to a value that matches your idle‑session policy (e.g., 300 seconds). This ensures inactive session states are reclaimed.