English for Streamlit Developers
Vocabulary for developers building data apps with Streamlit — widgets, session state, rerun behavior, and caching — for teams discussing internal tools and ML demos in English.
Streamlit turns a plain Python script into an interactive web app, without writing HTML, CSS, or JavaScript — widgets are just function calls, and the whole script reruns top to bottom on every interaction. That rerun model is the single biggest thing that trips people up, and it dominates most code review discussions. Here’s the English you need to talk about Streamlit apps clearly.
The Rerun Model
Rerun — Streamlit’s core execution model: the entire script re-executes from top to bottom every time a user interacts with a widget, rather than only updating the specific component that changed.
“That’s not a bug — every widget interaction triggers a full rerun, so any expensive computation without caching runs again from scratch.”
Widget — an interactive UI element (st.button, st.slider, st.text_input) that both renders a control and returns its current value inline in the script.
“Don’t store the widget’s value in a separate variable before using it elsewhere — just call the widget again where you need the value; Streamlit handles the state.”
Script execution top to bottom — the mental model that the whole file is a sequence of statements re-run in order on every interaction, not a persistent, stateful program in the traditional sense.
“Think of it as top-to-bottom execution on every click, not an event loop — that reframes why session state exists at all.”
Session State and Caching
Session state — a dictionary-like object (st.session_state) that persists values across reruns for a single user’s session, since local variables are reset on every rerun.
“That counter resets to zero on every click because it’s a local variable — move it into session state if you actually want it to persist across reruns.”
Callback — a function attached to a widget (on_click, on_change) that runs before the script rerun, often used to update session state in response to an interaction.
“Use a callback to update session state directly, instead of trying to read the widget’s new value and react to it after the rerun — the timing is wrong otherwise.”
Caching (st.cache_data / st.cache_resource) — decorators that store the result of an expensive function (a database query, a model load) so it isn’t recomputed on every rerun, keyed by the function’s arguments.
“Wrap that database call in
st.cache_data— right now it’s re-querying on every single widget interaction, which is why the app feels slow.”
Layout and Deployment
Container / columns — layout primitives (st.container, st.columns) used to organize widgets and outputs into a specific visual arrangement rather than relying on script order alone.
“Wrap those three metrics in
st.columns(3)instead of stacking them vertically — the dashboard reads much better side by side.”
Fragment — a section of the script that can rerun independently of the full page, introduced to avoid full-app reruns for isolated, frequently-updated widgets.
“That live-updating chart doesn’t need to trigger a full app rerun — mark it as a fragment so only that section refreshes.”
Common Mistakes
- Saying “the app is slow” without specifying whether it’s an uncached expensive computation, or simply the expected cost of a full rerun on every interaction.
- Storing values in local variables that need to persist across interactions, instead of using session state, then being confused why state “resets.”
- Forgetting that caching is keyed by function arguments, and being surprised when a cached function reruns anyway because one argument (like a mutable object) changed identity.
Practice Exercise
- Explain, in two sentences, why a variable defined mid-script gets reset every time a user clicks a button in a Streamlit app.
- Write a short PR description for wrapping a slow database call in
st.cache_datato fix a sluggish dashboard. - Draft a code review comment explaining why a counter needs to live in session state rather than a plain local variable.