Uv Workflow

Quick Reference

Project Setup

uv init                     # Create app project
uv init --package           # Create package (src/ layout)
uv init --lib               # Create library

Dependencies

uv add requests             # Add dependency
uv add -d pytest            # Add dev dependency
uv add 'requests>=2.28'     # With version constraint
uv remove requests          # Remove dependency
uv lock --upgrade           # Update all dependencies

Running Code

uv run python main.py       # Run script in project env
uv run pytest               # Run tools with dependencies
uvx ruff check .            # Run standalone tool (isolated)

Environment

uv sync                     # Sync env with lockfile
uv sync --all-groups        # Include all dependency groups
uv python install 3.11      # Install Python version
uv python pin 3.11          # Pin project to version

Critical Rules

Always Use uv run

Wrong - bypasses project environment:

python main.py
pytest

Correct - uses project environment:

uv run python main.py
uv run pytest

uv run vs uvx

Gotcha: uvx pytest won't see your project code!

Project Structure

uv creates this automatically:

my-project/
├── .venv/              # Auto-created, git-ignored
├── .python-version     # Python version pin
├── pyproject.toml      # Project config
├── uv.lock             # Deterministic lockfile (commit this!)
└── src/                # Source code (if --package)

Dependency Groups

# pyproject.toml
[project]
dependencies = ["requests", "click"]

[dependency-groups]
dev = ["pytest", "black", "ruff"]
docs = ["sphinx"]
test = ["pytest-cov"]

uv add -d pytest              # Add to dev group
uv add --group docs sphinx    # Add to named group
uv sync --group docs          # Install specific group
uv sync --all-groups          # Install all groups

Reference Files

• references/commands.md - Complete command reference
• references/workflows.md - Common workflows and patterns
• references/gotchas.md - Important gotchas and troubleshooting

Common Workflows

New Project

uv init my-project
cd my-project
uv add requests click
uv add -d pytest black ruff
uv run python -c "print('Ready!')"

Existing Project (clone)

git clone repo
cd repo
uv sync --all-groups    # Install from lockfile
uv run pytest           # Run tests

Update Dependencies

uv lock --upgrade                    # Update all
uv lock --upgrade-package requests   # Update specific
uv sync                              # Apply updates

Fresh Start (troubleshooting)

rm -rf .venv uv.lock
uv sync

Files to Commit