Introduction
Single-page Streamlit apps hit a wall around 200 lines: the UI becomes a wall of if/else blocks and the sidebar turns into a maze. Multipage apps fix this — one file per page, automatic navigation, and shared state across pages.
This post covers the modern (file-based) approach, introduced in Streamlit 1.16 and now the standard.
File structure
my_app/
├── Home.py # entry point (landing page)
├── pages/
│ ├── 1_Dashboard.py
│ ├── 2_Settings.py
│ └── 3_About.py
├── utils.py # shared helpers
├── .streamlit/
│ └── secrets.toml
└── requirements.txt
Streamlit auto-discovers pages/*.py and builds the sidebar navigation. The number prefix controls order.
Step 1: Home page (entry point)
# Home.py
import streamlit as st
st.set_page_config(page_title="My App", page_icon="🏠", layout="wide")
st.title("🏠 Welcome")
st.write("Use the sidebar to navigate.")
# Shared state (persists across pages within a session)
if "counter" not in st.session_state:
st.session_state.counter = 0
st.metric("Shared counter", st.session_state.counter)
Step 2: A page
# pages/1_Dashboard.py
import streamlit as st
import sys, os
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
from utils import load_data
st.set_page_config(page_title="Dashboard", page_icon="📊")
st.title("📊 Dashboard")
# Read shared state
st.write(f"Counter from home: {st.session_state.get('counter', 0)}")
# Increment
if st.button("Increment"):
st.session_state.counter = st.session_state.get("counter", 0) + 1
st.rerun()
data = load_data()
st.dataframe(data)
Step 3: Shared helpers
# utils.py
import pandas as pd
import streamlit as st
@st.cache_data
def load_data():
return pd.read_csv("data.csv")
def require_login():
if not st.session_state.get("logged_in"):
st.warning("Please log in first.")
st.stop()
Import in any page with from utils import .... The sys.path trick above makes imports work regardless of how Streamlit launches the app.
Step 4: Page config per page
Each page can set its own title, icon, and layout:
st.set_page_config(
page_title="Settings",
page_icon="⚙️",
layout="centered", # or "wide"
initial_sidebar_state="expanded",
)
Set this as the first Streamlit call on each page (before any other st.*).
Step 5: Hide pages conditionally
# pages/2_Admin.py
import streamlit as st
if not st.session_state.get("is_admin"):
st.stop() # page won't render; still shows in nav though
st.title("Admin panel")
To fully hide from the sidebar, use st.navigation (new in 1.36+):
# Home.py (entry point)
import streamlit as st
pages = [
st.Page("Home.py", title="Home", icon="🏠"),
st.Page("pages/1_Dashboard.py", title="Dashboard", icon="📊"),
]
if st.session_state.get("is_admin"):
pages.append(st.Page("pages/2_Admin.py", title="Admin", icon="🔐"))
nav = st.navigation(pages)
nav.run()
st.navigation gives you full control over which pages appear and their order.
Step 6: Shared state patterns
Pattern A: session_state (in-memory, per-user)
# Set on one page
st.session_state.user = {"name": "Galvan", "role": "admin"}
# Read on another
user = st.session_state.get("user")
Persists across pages within the same browser session. Lost on tab close.
Pattern B: query params (URL state)
# Read from URL: ?tab=settings
params = st.query_params
tab = params.get("tab", "home")
st.query_params["tab"] = "settings" # updates the URL
Good for shareable links and deep linking.
Pattern C: persistent (database)
For state that survives sessions, use Supabase or a file. Store a user ID in session_state, fetch their data from the DB on each page.
Step 7: Page groups (sections)
With st.navigation, group pages:
pages = {
"Main": [
st.Page("Home.py", title="Home", icon="🏠"),
st.Page("pages/1_Dashboard.py", title="Dashboard", icon="📊"),
],
"Account": [
st.Page("pages/3_Settings.py", title="Settings", icon="⚙️"),
st.Page("pages/4_Logout.py", title="Logout", icon="🚪"),
],
}
nav = st.navigation(pages)
nav.run()
Renders as grouped sections in the sidebar.
Common mistakes
- Import errors —
pages/*.pycan’t import from the root by default. Addsys.path.insert(0, ...)or use autils.pyat the root with the path trick. - Multiple
set_page_config— only the first call wins. Set it once per page, at the top. - State not shared —
st.session_stateIS shared across pages in the same session. If it’s not persisting, you’re probably using a local variable. - File naming — prefix with numbers for order (
1_Dashboard.py). Streamlit sorts alphabetically. - Stale cache —
@st.cache_datais global; clear it with.clear()when data changes.
Key Concepts
- File-based routing = one file per page in
pages/ st.navigation= programmatic page control (groups, conditional pages)st.session_state= shared state across pagesst.query_params= URL state for deep linkingst.Page= page definition with title/icon
What to Try Next
- Add auth and gate pages behind login.
- Persist user data with Supabase.
- Use
st.navigationfor a custom sidebar with user info. - Combine with caching for fast page loads.
FAQ
Streamlit multipage vs single file with tabs?
Multipage = separate URLs, better for distinct sections. Tabs = one page, better for related views. Use multipage for apps with 3+ distinct screens.
Can I have nested pages (sub-routes)?
Not natively. Flatten your structure: 1_Dashboard.py, 2_Dashboard_Detail.py. Or use query params for sub-views.
How do I deploy a multipage app?
Same as single-page: push to GitHub, deploy on Streamlit Cloud. The pages/ folder is auto-detected. No config needed.