- name
- python-uv-project-setup
- description
- Use when initializing a Python project or script, adding dependencies, or running commands with uv, especially to avoid pip install and direct python/pytest usage.
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(neverpip install). - Run commands with
uv run(never directpythonorpytest).
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 tyScript 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.pyExample
Issue: "Missing fastapi. Tests fail."
Fix:
uv add fastapi
uv run pytestCommon Mistakes
- Running
pip installfirst and only switching to uv after it fails. - Running
pythonorpytestdirectly instead ofuv 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, orpytestdirectly.