Show API reference for

st.rerun

Rerun the script immediately.

When st.rerun() is called, Streamlit halts the current script run and executes no further statements. Streamlit immediately queues the script to rerun.

When using st.rerun in a fragment, you can scope the rerun to the fragment. However, if a fragment is running as part of a full-app rerun, a fragment-scoped rerun is not allowed.

Function signature[source]

st.rerun(scope="app")

Parameters

scope ("app", "fragment", str, int, or list of str/int)

Specifies what part of the app should rerun.

  • "app" (default): the full app reruns.
  • "fragment": Streamlit only reruns the fragment from which this command is called. Only valid inside a fragment during a fragment rerun. Raises StreamlitAPIException during a full-app rerun or outside of a fragment.
  • A fragment key (str or int) or list of fragment keys: reruns only the named fragment(s), replacing the interaction's default rerun. The key must match the key argument passed to @st.fragment(key=...). An int key is normalized to its string representation. An unknown key raises StreamlitAPIException. This form is only valid from a widget callback (on_change / on_click); calling it from the main script body or a fragment body raises StreamlitAPIException. If a sibling callback in the same interaction returns normally or calls st.rerun(), the result escalates to a full-app rerun.

Note

When a keyed rerun replaces the interaction default, only the targeted fragment(s) rerun. Other widgets changed in the same interaction (e.g. form fields submitted alongside the callback) have their values applied to session state, but they won't render until the next full-app rerun.

Examples

Rerun a named fragment from a widget callback:

import streamlit as st

@st.fragment(key="charts")
def charts():
    st.line_chart({"data": [1, 2, 3]})

charts()
st.button(
    "Refresh charts",
    on_click=lambda: st.rerun("charts"),
)

Rerun multiple fragments at once:

@st.fragment(key="table")
def table():
    st.dataframe({"col": [1, 2, 3]})

table()
st.button(
    "Refresh all",
    on_click=lambda: st.rerun(["charts", "table"]),
)

Caveats for st.rerun

st.rerun is one of the tools to control the logic of your app. While it is great for prototyping, there can be adverse side effects:

  • Additional script runs may be inefficient and slower.
  • Excessive reruns may complicate your app's logic and be harder to follow.
  • If misused, infinite looping may crash your app.

In many cases where st.rerun works, callbacks may be a cleaner alternative. Containers may also be helpful.

A simple example in three variations

Using st.rerun to update an earlier header
Python
import streamlit as st

if "value" not in st.session_state:
    st.session_state.value = "Title"

##### Option using st.rerun #####
st.header(st.session_state.value)

if st.button("Foo"):
    st.session_state.value = "Foo"
    st.rerun()
Using a callback to update an earlier header
Python
##### Option using a callback #####
st.header(st.session_state.value)

def update_value():
    st.session_state.value = "Bar"

st.button("Bar", on_click=update_value)
Using containers to update an earlier header
Python
##### Option using a container #####
container = st.container()

if st.button("Baz"):
    st.session_state.value = "Baz"

container.header(st.session_state.value)
star

Tip

Want a new st.rerun feature or found a bug? Browse open issues and react with a 👍 on the initial post of the ones that matter to you. Your votes help us prioritize what to work on next.

arrow_backPrevious: st.fragmentarrow_forwardNext: st.stop
forum

Still have questions?

Our forums are full of helpful information and Streamlit experts.