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.