Setting up Python environments for Streamlit apps. Use when creating a new project or managing dependencies. Covers uv for dependency management and running apps.
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.
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/icon_name:)st.pills(), st.segmented_control()When setting up a new project or fixing an existing one, always check and update the streamlit version.
If uv is available, here's how to set up a Streamlit project.
For simple apps, just create a virtual environment:
uv venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
uv pip install streamlit
Run with:
streamlit run streamlit_app.py
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 environmentRun with:
uv run streamlit run streamlit_app.py
Avoid setting options unless you have a specific reason:
streamlit run streamlit_app.py --server.headless true # Only for automated/CI environments
# With venv approach
uv pip install plotly snowflake-connector-python
# With full project (uv init)
uv add plotly snowflake-connector-python
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 buildsName your main file streamlit_app.py for consistency. This is what Streamlit expects by default.
What goes in the main module:
[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",
]