| name | setting-up-streamlit-environment |
| description | Setting up Python environments for Streamlit apps. Use when creating a new project or managing dependencies. Covers uv for dependency management and running apps. |
| license | Apache-2.0 |
Streamlit environment
Use whatever dependency management the project already has (pip, poetry, conda, etc.). If starting fresh and uv is available, it's a good default—fast, reliable, and creates isolated environments automatically.
If uv is not installed, ask the user before installing it.
CRITICAL: Always Use Latest Streamlit
Always specify streamlit>=1.53.0 (or latest) in dependencies. Many Streamlit features and patterns in these skills require recent versions. Older streamlit versions will cause errors with:
- Material icons (
:material/icon_name:)
st.pills(), st.segmented_control()- Modern caching decorators
- Navigation APIs
When setting up a new project or fixing an existing one, always check and update the streamlit version.
Using uv
If uv is available, here's how to set up a Streamlit project.
Quick start (venv only)
For simple apps, just create a virtual environment:
uv venv
source .venv/bin/activate
uv pip install streamlit
Run with:
streamlit run streamlit_app.py
Full project setup
For larger projects or when you need reproducible builds:
uv init my-streamlit-app
cd my-streamlit-app
uv add streamlit
This creates:
pyproject.toml with dependenciesuv.lock for reproducible builds.venv/ virtual environment
Run with:
uv run streamlit run streamlit_app.py
With options
Avoid setting options unless you have a specific reason:
streamlit run streamlit_app.py --server.headless true
Add dependencies
uv pip install plotly snowflake-connector-python
uv add plotly snowflake-connector-python
Project structure
Keep it simple. For most apps:
my-streamlit-app/
├── .venv/
└── streamlit_app.py
Only add more when needed:
app_pages/ → Only for multi-page apps.streamlit/config.toml → Only if customizing theme or settings.streamlit/secrets.toml → Only if using secrets (add to .gitignore)pyproject.toml → Only if using uv init for reproducible builds
Convention
Name your main file streamlit_app.py for consistency. This is what Streamlit expects by default.
What goes in the main module:
- When using navigation: it's a router that defines pages and runs them
- When there's no navigation: it's the home page with your main content
pyproject.toml Example
[project]
name = "my-streamlit-app"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
"streamlit>=1.53.0",
"plotly>=5.0.0",
"snowflake-connector-python>=3.0.0",
]
[tool.uv]
dev-dependencies = [
"pytest>=8.0.0",
]
References
