| name | organizing-streamlit-code |
| description | Organizing Streamlit code for maintainability. Use when structuring apps with separate modules and utilities. Covers separation of concerns, keeping UI code clean, and import patterns. |
| license | Apache-2.0 |
Streamlit code organization
For most simple apps, keep everything in one file—it's cleaner and more straightforward. The app file should read like a normal Python script for data processing, with a few Streamlit commands sprinkled in.
Name the main file streamlit_app.py (Streamlit's default).
When to split
Keep in one file (most apps):
- Apps under ~1000 lines
- One-off scripts and prototypes
- Apps where logic is straightforward
Consider splitting when:
- Data processing is complex (50+ lines of non-UI code)
- Multiple pages share logic
- You want to test business logic separately
If splitting makes sense, here's how to organize it.
Directory structure
my-app/
├── streamlit_app.py # Main entry point
├── app_pages/ # Page UI modules
│ ├── dashboard.py
│ └── settings.py
└── utils/ # Business logic & helpers
├── data.py
└── api.py
Separating UI from logic
When you do split, keep Streamlit files focused on UI and move complex logic to utility modules:
import streamlit as st
from utils.data import load_sales_data, compute_metrics
st.title("Sales Dashboard")
start = st.date_input("Start")
end = st.date_input("End")
data = load_sales_data(start, end)
metrics = compute_metrics(data)
st.metric("Revenue", f"${metrics['revenue']:,.0f}")
st.dataframe(data)
Avoid if name == "main"
Streamlit apps run the entire file on each interaction. Don't use the main guard in Streamlit files.
if __name__ == "__main__":
main()
import streamlit as st
st.title("My App")
The main guard is fine in utility modules for quick testing:
def load_data(path):
...
if __name__ == "__main__":
print(load_data("test.csv"))
References
