Python uv Project Setup
Overview
Use uv for environments, dependency management, and command execution. Core principle: always install and run through uv, not pip/python directly.
Non-Negotiable Rules
-
Install dependencies with uv add (never pip install ).
-
Run commands with uv run (never direct python or pytest ).
Quick Reference
Task Command
Initialize project uv init <name>
Add dependency uv add <package>
Add dev dependency uv add --dev <package>
Run Python uv run python <file.py>
Run pytest uv run pytest
Sync deps uv sync
Workflow
Project setup (package)
uv init my-project cd my-project uv add loguru typer uv add --dev ruff pytest pytest-cov ty
Script setup (single file)
If you are working with a script, still install with uv and run via uv:
uv add fastapi uv run python script.py
Example
Issue: "Missing fastapi. Tests fail."
Fix:
uv add fastapi uv run pytest
Common Mistakes
-
Running pip install first and only switching to uv after it fails.
-
Running python or pytest directly instead of uv run .
Rationalizations to Reject
Excuse Reality
"pip install is faster for a quick fix" It bypasses the project environment and drifts from uv-managed state.
"I can run python/pytest directly this once" Direct runs skip uv's environment and can break reproducibility.
Red Flags
- Any instruction that uses pip install , python , or pytest directly.