Streamlit

When using parallel fragments (fragments running concurrently on worker threads), certain Streamlit APIs are prohibited to prevent non-deterministic UI behavior, cursor races, and disruptive side effects.

Prohibited during parallel execution (worker threads):

• @st.dialog: You cannot open a dialog while multiple fragments are running in parallel. However, you can open a dialog during a sequential fragment rerun (e.g., a button click within a fragment that triggers only that fragment to rerun).
• st.switch_page: Navigating to a new page is prohibited during a parallel batch because it would cancel all other active parallel threads and cause race conditions on the destination page. This is allowed during sequential fragment reruns.
• External container writes: You cannot write elements (widgets or non-widgets) to containers located outside the fragment's own delta path (e.g., st.sidebar or a parent st.container()). All writes must be contained within the fragment body.

Allowed during parallel execution:

• Most standard Streamlit APIs for element rendering are safe due to internal synchronization.
• Execution control commands like st.rerun and st.stop are handled via cooperative cancellation.

If you attempt a prohibited operation, Streamlit will raise a StreamlitAPIException.

The framework collects three categories of metrics:

Server Metrics (sampled every 500ms via psutil)

• memory_rss_mb: Resident Set Size in MB (start/end)
• memory_rss_mb_peak: Peak RSS during test
• memory_rss_mb_avg: Average RSS during test
• memory_rss_mb_growth: RSS growth from start to end
• cpu_percent_avg: Average CPU utilization
• cpu_percent_peak: Peak CPU utilization
• thread_count_max: Maximum number of server threads

Session Metrics (per simulated user)

• initial_load_time_ms: Time to first complete app render
• rerun_times_ms: Times for script reruns after interactions
• errors: Any errors encountered in the session

Aggregate Metrics

• sessions_completed: Successful sessions
• sessions_failed: Failed or timed-out sessions
• initial_load_time_ms: Percentiles (min, max, mean, p50, p95, p99) for initial load
• rerun_time_ms: Percentiles (min, max, mean, p50, p95, p99) for reruns

You can prevent stateful widgets from triggering a full script rerun every time their value changes by passing on_change="ignore". This is useful for batching multiple parameter adjustments (like sliders or selectboxes) before executing expensive computations or data processing.

How it works

1. Frontend Update: The widget's visual state updates immediately in the browser.
2. Value Storage: The new value is stored in the frontend state but is not immediately sent to the Python backend.
3. No Rerun: The Streamlit script does not rerun.
4. Sync on Next Rerun: When a rerun is eventually triggered (e.g., by clicking an st.button), the frontend flushes the updated values to the backend. Your Python code will then receive the new values via the widget's return value or st.session_state.

Warning: Values modified with on_change="ignore" are held in browser memory only. If the user refreshes the page before a rerun occurs, these changes are lost.

# Adjust parameters without triggering reruns
threshold = st.slider("Threshold", 0.0, 1.0, 0.5, on_change="ignore")
learning_rate = st.slider("Learning Rate", 0.001, 0.1, 0.01, on_change="ignore")

# Only run expensive computation when user clicks
if st.button("Train Model"):
    # On this rerun, 'threshold' and 'learning_rate' will reflect the new values
    model = train_model(threshold, learning_rate)

Streamlit uses a top-to-bottom rerun model where the entire script re-executes on every widget interaction. To avoid full-script reruns for specific UI regions, you can use @st.fragment.

Scoped Reruns with @st.fragment

A fragment is a function whose execution is scoped. When a widget inside a fragment changes, only that fragment re-executes, rather than the entire script. This allows for partial re-evaluation of specific UI components (like a single chart or a filter bar) without the overhead of a full app rerun.

Targeted Reruns (Proposed/Upcoming)

The framework is evolving to allow a widget's event handler to trigger a rerun of a specific, addressable fragment from outside that fragment. This is achieved by passing the fragment's unique key to st.rerun(). This enables cross-fragment communication (e.g., a filter widget in one part of the app triggering a rerun of a data visualization fragment in another) while maintaining the deterministic, re-computation-based model of Streamlit.