Explains Streamlit's internal architecture including backend runtime, frontend rendering, and WebSocket communication. Use when debugging cross-layer issues, understanding how features work end-to-end, planning architectural changes, or onboarding to the codebase. Covers ForwardMsg/BackMsg protocol, script rerun model, element tree, widget state management, and more.
Streamlit is a client-server application with bidirectional WebSocket communication using Protocol Buffers.
Use this file as a quick mental model and navigation index; use references/backend.md, references/frontend.md, and references/communication.md for implementation details.
| Concept | Description | Key files |
|---|---|---|
| Command | Any function exposed in Streamlit's public API (st.* namespace). Commands can create elements/widgets, control execution flow, or configure app behavior. | lib/streamlit/delta_generator.py, lib/streamlit/elements/, lib/streamlit/commands/ |
| Element | Umbrella term for all UI components in Streamlit: widgets, containers, and display elements. Represented in Element.proto as a oneof union of ~50+ types. | proto/streamlit/proto/Element.proto, lib/streamlit/elements/ |
| Widget | Interactive element (button, slider, text_input) that triggers reruns on user interaction. Value accessible via return value or st.session_state. Some elements become widgets conditionally (e.g., dataframe/chart with on_select). | lib/streamlit/elements/widgets/, frontend/lib/src/components/widgets/ |
| Display Element | Non-interactive element (text, markdown, image, chart) that renders content without triggering reruns by itself. | lib/streamlit/elements/, frontend/lib/src/components/elements/ |
| Container | Layout block that groups elements spatially (sidebar, columns, expander, tabs, form). Represented as BlockNode in the element tree. | lib/streamlit/elements/layouts.py, Block.proto |
| DeltaGenerator | The st object; API entry point that queues UI deltas. Uses mixin pattern to compose all st.* commands. | lib/streamlit/delta_generator.py |
| Session State | Per-session dictionary (st.session_state) persisting data across reruns. Stores widget values and user variables. | lib/streamlit/runtime/state/session_state.py |
| Rerun | Re-execution of the user script for the current page. Triggered by widget interactions, st.rerun(), file changes, or fragment timers. Rebuilds the element tree while preserving session state. | lib/streamlit/runtime/scriptrunner/script_runner.py, lib/streamlit/commands/execution_control.py |
| Form | Container (st.form) that batches widget inputs, deferring reruns until form submission. | lib/streamlit/elements/form.py, WidgetStateManager.ts |
| Fragment | Decorator (@st.fragment) enabling partial reruns of specific UI sections without full script re-execution. | lib/streamlit/runtime/fragment.py |
| Caching | Decorators (@st.cache_data, @st.cache_resource) that memoize function results to avoid redundant computation. | lib/streamlit/runtime/caching/ |
| Pages | Multipage app system using st.navigation() and st.Page() or auto-discovery from pages/ directory. | lib/streamlit/navigation/, lib/streamlit/runtime/pages_manager.py |
| Config | App configuration via .streamlit/config.toml controlling server, client, and theme settings. | lib/streamlit/config.py, lib/streamlit/config_option.py |
| Theming | Customizable UI themes (Light/Dark/Custom) defined in config or via theme editor. | lib/streamlit/runtime/theme_util.py, frontend/lib/src/theme/ |
| Secrets | Secure credential storage via .streamlit/secrets.toml (local) or platform settings (deployed). Accessed via st.secrets. | lib/streamlit/runtime/secrets.py |
| Connection | Database/service abstraction (st.connection) with built-in caching and secrets integration. | lib/streamlit/connections/ |
| Custom Components | User-built extensions using React/iframe. v1 (legacy): declare_component() API. v2 (current): Bidirectional components with improved state management. | frontend/component-lib/, frontend/component-v2-lib/, lib/streamlit/components/v1/, lib/streamlit/components/v2/ |
| Static File Serving | Files in static/ directory served directly via /app/static/* (when static serving is enabled). | lib/streamlit/web/server/server.py, lib/streamlit/web/server/starlette/starlette_routes.py |
| App Testing | Testing framework (AppTest) for simulating user interactions and inspecting rendered output. | lib/streamlit/testing/ |
flowchart TB
subgraph Backend["Backend (Python)"]
Script[User Script]
DG[DeltaGenerator]
Runtime[Runtime/AppSession]
end
subgraph Protocol["WebSocket + Protobuf"]
FM[ForwardMsg]
BM[BackMsg]
end
subgraph Frontend["Frontend (React)"]
App[App.tsx]
Tree[AppRoot Tree]
Renderer[ElementNodeRenderer]
WSM[WidgetStateManager]
end
Script --> DG
DG --> FM
FM --> App
App --> Tree
Tree --> Renderer
Renderer --> WSM
WSM -->|User interaction| BM
BM --> Runtime
Runtime -->|Rerun| Script
Key insight: Script execution is rerun-driven: most widget interactions trigger reruns (full app or fragment-scoped). State persists via st.session_state and caching decorators.
Streamlit's execution model differs from traditional web frameworks:
Rerun triggers:
st.rerun(): Explicit programmatic rerun@st.fragment(run_every=...) periodic rerunsExecution order nuances:
on_change/on_click handlers run before the main script body@st.fragment usually rerun only that fragmentst.stop(), st.rerun(), st.switch_page() raise exceptions to halt/redirect executionSession isolation:
AppSession with its own SessionStateWhat persists across reruns (within a session):
st.session_state values@st.cache_data, @st.cache_resource)What resets on each rerun:
SessionState)| Component | File | Purpose |
|---|---|---|
| Runtime | lib/streamlit/runtime/runtime.py | Singleton managing app lifecycle and sessions |
| AppSession | lib/streamlit/runtime/app_session.py | Per-browser-tab: ScriptRunner + SessionState + ForwardMsgQueue |
| ScriptRunner | lib/streamlit/runtime/scriptrunner/script_runner.py | Executes user scripts in separate thread |
| DeltaGenerator | lib/streamlit/delta_generator.py | API entry point using mixin pattern |
| SessionState | lib/streamlit/runtime/state/session_state.py | Widget values and user variables |
| Elements | lib/streamlit/elements/ | Backend implementation of st.* commands |
For backend deep dive: See references/backend.md
| Component | File | Purpose |
|---|---|---|
| App | frontend/app/src/App.tsx | Central orchestrator |
| AppRoot | frontend/lib/src/render-tree/AppRoot.ts | Immutable element tree with 4 containers |
| ElementNodeRenderer | frontend/lib/src/components/core/Block/ElementNodeRenderer.tsx | Maps protos to React components |
| WidgetStateManager | frontend/lib/src/WidgetStateManager.ts | Widget state, forms, query params |
| ConnectionManager | frontend/connection/src/ConnectionManager.ts | WebSocket state machine |
For frontend deep dive: See references/frontend.md
| Proto | Purpose |
|---|---|
ForwardMsg.proto | Server to client: deltas, session events, navigation |
BackMsg.proto | Client to server: rerun requests with widget states |
Element.proto | ~50+ element types in oneof type union |
WidgetStates.proto | Widget values: trigger_value, string_value, bool_value, etc. |
Location: proto/streamlit/proto/
For protocol deep dive: See references/communication.md
BackMsg (ClientState) -> backend updates SessionState -> script rerun -> ForwardMsg deltas.
references/communication.md#widget-interaction-to-script-rerun[0, 2, 3]) to support efficient tree updates.
references/communication.md#delta-ui-changesactive_script_hash semantics: ForwardMsg.metadata.active_script_hash scopes node ownership across multipage and fragment reruns.
references/communication.md#forwardmsg-metadata-active_script_hashAppRoot maintains main, sidebar, event, and bottom containers with BlockNode/ElementNode.
references/frontend.md#element-tree-frontendlibsrcrender-treereferences/element-identity.md@st.fragment): Fragment interactions usually trigger fragment-scoped reruns and update only affected regions.
WidgetStateManager state, BackMsg.WidgetStates, backend SessionState, callbacks, and st.session_state.element.id can still let React preserve a leaf when it remains under the same rendered parent list.Deep dive: references/element-identity.md
DeltaGenerator composes st.* API via mixins.
references/backend.md#deltagenerator-libstreamlitdelta_generatorpyreferences/frontend.md#visitor-patternForwardMsg.hash + ref_hash with frontend ForwardMsgCache reduces bandwidth.
references/communication.md#message-cachingproto/streamlit/proto/<Element>.protooneof typelib/streamlit/elements/<element>.pyfrontend/lib/src/components/elements/<Element>/ or frontend/lib/src/components/widgets/<Element>/ (depending on element vs widget)make protobufSee wiki/new-feature-guide.md for a detailed implementation guide.
When making changes that impact any of the concepts documented here (Runtime, AppSession, DeltaGenerator, element tree, communication protocol, element identity, etc.), update the relevant sections in this skill's files (SKILL.md, references/backend.md, references/frontend.md, references/communication.md, references/element-identity.md) to keep them accurate.