aedelon/uv-workflow

UV Package Manager

Ultra-fast Python package installer and resolver written in Rust. 10-100x faster than pip.

Quick Reference

# Project lifecycle
uv init my-project          # Create project
uv add requests pandas      # Add deps
uv add --dev pytest ruff    # Add dev deps
uv remove package           # Remove
uv sync                     # Install all from pyproject.toml
uv lock                     # Generate/update lockfile
uv run pytest               # Run in venv (no activation needed)

# Virtual environments
uv venv                     # Create .venv
uv venv --python 3.12       # With specific Python
uv python install 3.12      # Install Python version
uv python pin 3.12          # Pin for project

# pip-compatible
uv pip install -r requirements.txt
uv pip freeze > requirements.txt

Project Setup Pattern

uv init my-project && cd my-project
uv python pin 3.12
uv add fastapi uvicorn pydantic
uv add --dev pytest ruff mypy black
mkdir -p src/my_project tests
uv run pytest

Creates: pyproject.toml, .python-version, uv.lock, .venv/

pyproject.toml Standard

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.31.0",
    "pydantic>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "ruff>=0.1.0",
    "mypy>=1.5.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
dev-dependencies = []

[tool.uv.workspace]
members = ["packages/*"]  # For monorepos

Lockfile Workflow

uv lock                     # Create/update uv.lock
uv sync --frozen            # Install exact versions (CI)
uv lock --upgrade           # Upgrade all
uv lock --upgrade-package requests  # Upgrade one
uv lock --check             # Verify lockfile is current
uv export --format requirements-txt > requirements.txt  # Export

Rule: Always commit uv.lock to version control.

Docker Integration

FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-editable

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /app/.venv .venv
COPY . .
ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "app.py"]

CI/CD (GitHub Actions)

name: Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v2
        with:
          enable-cache: true
      - run: uv python install 3.12
      - run: uv sync --all-extras --dev
      - run: uv run pytest
      - run: uv run ruff check .

Migration Guides

From pip

# Before: pip install -r requirements.txt
# After:
uv init
uv add -r requirements.txt

From poetry

# Before: poetry install
# After: uv already reads pyproject.toml
uv sync

From pip-tools

# Before: pip-compile && pip-sync
# After:
uv lock && uv sync --frozen

Key Commands

| Command | Purpose | |---------|---------| | uv init | Initialize project | | uv add PKG | Add dependency | | uv add --dev PKG | Add dev dependency | | uv remove PKG | Remove dependency | | uv sync | Install all deps | | uv sync --frozen | Install exact (CI) | | uv lock | Create/update lockfile | | uv run CMD | Run in venv | | uv venv | Create venv | | uv python install | Install Python | | uv python pin | Pin Python version | | uv cache clean | Clear cache |

Best Practices

1. Always use uv run instead of activating venv
2. Commit uv.lock to git
3. Use --frozen in CI for reproducible builds
4. Pin Python version with .python-version
5. Separate dev deps from production deps
6. Use workspaces for monorepos
7. Export requirements.txt for compatibility when needed