Question about st.cache_data TTL and Memory Cleanup

Open
#1,503 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Needs clarification
Activity status
Quiet
Tech stack
python
Domain
documentation

Research direction

The report names st.cache_data, TTL, max_entries, and cache-clearing APIs but no repository file or test. Start by locating the existing documentation for these APIs and checking whether it explains expiration and Python memory behavior. Done would require an agreed documentation scope and a clear explanation of the observed behavior and recommended approach.

Written by the indexing model from the issue text.

Description

bug needs triage

Scenario 1: User 1

I have a cached function with a TTL of 1 hour.

@st.cache_data(ttl=3600)
def load_data():

Steps
At 10:00 AM, User 1 runs the function.
The function caches a 1 GB DataFrame.
As the ttl is 1 Hr it should reduce the memory consumption & go down to 100 mb after 2 Hour
Also no one perfrom any operation on application after that test
Even after the TTL has expired for several hours, the application's process memory remains around 1 GB. The memory does not appear to be released automatically.

Questions
Is this the expected behavior?
Does Streamlit have any background process that automatically removes expired cache entries from memory after the TTL expires?
When the TTL expires, is only the cache entry marked as expired, or is the Python memory also released?
Scenario 2: User 2

I also tested the application with a second user.

Steps
At 4:00 PM, User 2 calls the same cached function with different input parameters.
The function generates a new cached result of approximately 800 MB.
Observation

Instead of the application's memory decreasing from 1 GB to 800 MB, the total process memory increases, suggesting that the previous cached object may still be occupying memory.

Questions
Is this expected behavior?
Does Streamlit keep the expired cache in memory until it is evicted or manually cleared?
If the memory is managed by Python, what is the recommended approach to release the memory used by expired cache entries?
What I Have Tried
I explored using max_entries to limit cache growth.
However, my application contains many cached functions, and applying max_entries to all of them is not practical because it increases cache evictions, leading to more recomputation and slower page performance.
I also tried:
st.cache_data.clear()
function_name.clear()

These clear the cache manually, but they are not practical for my application because they invalidate cached data for all users or for an entire function.

Dominant language
JavaScript
Stars
178
Forks
705
Avg merge
1d 13h
Merged PRs (30d)
39

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from streamlit/docs

All issues in streamlit/docs

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.