Skip to content

docs: clarify default rerun behavior #1578

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sfc-gh-lwilby-1 merged 3 commits into from
Oct 19, 2026
Merged

docs: clarify default rerun behavior #1578

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
62f06e8
docs: clarify default rerun behavior
sfc-gh-lwilby-1 Oct 15, 2026
333e3f4
docs: mention ignored widget reruns
sfc-gh-lwilby-1 Oct 15, 2026
4f6eb4d
docs: distinguish variables from Session State
sfc-gh-lwilby-1 Oct 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions content/develop/concepts/architecture/session-state.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ keywords: session state, statefulness, st.session_state, callbacks, state manage

## What is State?

We define access to a Streamlit app in a browser tab as a **session**. For each browser tab that connects to the Streamlit server, a new session is created. Streamlit reruns your script from top to bottom every time you interact with your app. Each reruns takes place in a blank slate: no variables are shared between runs.
We define access to a Streamlit app in a browser tab as a **session**. For each browser tab that connects to the Streamlit server, a new session is created. By default, Streamlit reruns your script from top to bottom every time you interact with your app. Some widgets accept `on_change="ignore"` to update without triggering a rerun; Python receives the new value on the next rerun. You can also use [forms](/develop/concepts/architecture/forms) to batch interactions until submission or [fragments](/develop/concepts/architecture/fragments) to rerun only part of your script. Each full-script rerun starts with a blank slate for regular Python variables, but values stored in Session State persist across full-script and fragment reruns.

Session State is a way to share variables between reruns, for each user session. In addition to the ability to store and persist state, Streamlit also exposes the ability to manipulate state using Callbacks. Session state also persists across pages inside a [multipage app](/develop/concepts/multipage-apps).
Session State is scoped to each user session. Streamlit also exposes the ability to manipulate state using Callbacks. Session State persists across pages inside a [multipage app](/develop/concepts/multipage-apps).

In this guide, we will illustrate the usage of **Session State** and **Callbacks** as we build a stateful Counter app.

Expand Down
20 changes: 13 additions & 7 deletions content/get-started/fundamentals/main-concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,17 +80,23 @@ If you are using Streamlit version 1.10.0 or higher, your main script should liv
## Data flow

Streamlit's architecture allows you to write apps the same way you write plain
Python scripts. To unlock this, Streamlit apps have a unique data flow: any
time something must be updated on the screen, Streamlit reruns your entire
Python script from top to bottom.
Python scripts. To unlock this, Streamlit apps have a unique data flow: by
default, when something must be updated on the screen, Streamlit reruns your
entire Python script from top to bottom.

This can happen in two situations:
By default, a full-script rerun happens in two situations:

- Whenever you modify your app's source code.

- Whenever a user interacts with widgets in the app. For example, when dragging
a slider, entering text in an input box, or clicking a button.

Some widgets accept `on_change="ignore"` to update without triggering a rerun;
Python receives the new value on the next rerun. You can also use
[forms](/develop/concepts/architecture/forms) to batch widget input until
submission or [fragments](/develop/concepts/architecture/fragments) to rerun
only part of your app.

Whenever a callback is passed to a widget via the `on_change` (or `on_click`) parameter, the callback will always run before the rest of your script. For details on the Callbacks API, please refer to our [Session State API Reference Guide](/develop/api-reference/caching-and-state/st.session_state#use-callbacks-to-update-session-state).

And to make all of this fast and seamless, Streamlit does some heavy lifting
Expand Down Expand Up @@ -277,9 +283,9 @@ st.write(x, 'squared is', x * x)
```

On first run, the app above should output the text "0 squared is 0". Then
every time a user interacts with a widget, Streamlit simply reruns your script
from top to bottom, assigning the current state of the widget to your variable
in the process.
with the default widget behavior, every time a user interacts with a widget,
Streamlit simply reruns your script from top to bottom, assigning the current
state of the widget to your variable in the process.

For example, if the user moves the slider to position `10`, Streamlit will
rerun the code above and set `x` to `10` accordingly. So now you should see the
Expand Down