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.