/uv-workflow

name: uv-workflow
description: |-
  Master uv package manager for Python: project setup, dependency management, virtual environments,
  lockfiles, CI/CD integration, Docker builds, and migration from pip/poetry.
  MUST BE USED when user mentions: "uv", "uv add", "uv run", "uv sync", "uv init", "uv lock",
  "uv venv", "uv pip", "pyproject.toml", "python project setup", "python dependencies",
  "virtual environment", "venv", "pip install", "poetry to uv", "migrate from pip",
  "lockfile python", "requirements.txt", "setup.py", "pip freeze", "uv tool",
  "install package", "add dependency", "python environment", "new python project",
  "package manager python", "create project", "uv export", "uv cache", "uv python".
  10-100x faster than pip. Covers init, add, sync, lock, run, Docker, CI/CD.
  NOT for npm/pnpm/yarn (JS toolchain), Rust cargo, or deployment (use deployment-assistant).
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Grep
  - Glob
  - mcp__context7__resolve-library-id
  - mcp__context7__get-library-docs

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