uv
in Practice

Containers

• Production Dockerfile patterns
• Multi-stage builds with distroless / scratch
• BuildKit cache mounts and bind-mounted dev
• GPU base images for ML

Single-stage, fast and correct

# syntax=docker/dockerfile:1.7
FROM ghcr.io/astral-sh/uv:0.5-python3.12-bookworm-slim

ENV UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy \
    UV_PROJECT_ENVIRONMENT=/app/.venv \
    PATH=/app/.venv/bin:$PATH \
    PYTHONUNBUFFERED=1

WORKDIR /app

# 1. Cache dependency install separately
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-install-project --no-dev

# 2. Copy source & install the project
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev

EXPOSE 8000
CMD ["uvicorn", "myapp.main:app", \
     "--host", "0.0.0.0", "--port", "8000"]

Builder stage → distroless runtime

# syntax=docker/dockerfile:1.7
# ── builder ───────────────────────────────
FROM ghcr.io/astral-sh/uv:0.5-python3.12-bookworm-slim AS builder

ENV UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy \
    UV_PYTHON_DOWNLOADS=never \
    UV_PROJECT_ENVIRONMENT=/app/.venv

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-install-project --no-dev
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev

# ── runtime ───────────────────────────────
FROM gcr.io/distroless/python3-debian12:nonroot

WORKDIR /app
COPY --from=builder --chown=nonroot:nonroot /app /app
ENV PATH="/app/.venv/bin:$PATH"

EXPOSE 8000
ENTRYPOINT ["/app/.venv/bin/python", "-m", "uvicorn"]
CMD ["myapp.main:app", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "8000:8000"
    volumes:
      - .:/app
      - uv-cache:/root/.cache/uv
      - venv:/app/.venv          # named volume!
    environment:
      UV_LINK_MODE: copy
      UV_COMPILE_BYTECODE: "1"
    command: >
      uv run uvicorn myapp.main:app
        --host 0.0.0.0 --reload

volumes:
  uv-cache:
  venv:

Matrix across Python + OS

name: ci
on: [push, pull_request]

jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python: ["3.11", "3.12", "3.13"]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4

      - uses: astral-sh/setup-uv@v3
        with:
          version: "0.5.4"
          enable-cache: true
          cache-dependency-glob: |
            **/uv.lock
            **/pyproject.toml

      - run: uv python install ${{ matrix.python }}

      - run: uv sync --frozen --all-groups

      - run: uv run ruff check . --output-format=github
      - run: uv run mypy src/
      - run: uv run pytest -q --cov --cov-report=xml

      - uses: codecov/codecov-action@v4
        with:
          files: coverage.xml

GitLab CI

image: ghcr.io/astral-sh/uv:0.5-python3.12-bookworm-slim

variables:
  UV_CACHE_DIR: "$CI_PROJECT_DIR/.uv-cache"
  UV_LINK_MODE: copy

cache:
  key:
    files: [uv.lock]
  paths:
    - .uv-cache/
    - .venv/

stages: [lint, test, build]

lint:
  stage: lint
  script:
    - uv sync --frozen --all-groups
    - uv run ruff check .

test:
  stage: test
  script:
    - uv sync --frozen --all-groups
    - uv run pytest -q --cov

Install pre-commit via uv tool

# once per machine
uv tool install pre-commit \
  --with pre-commit-uv

# then in the repo
pre-commit install
pre-commit autoupdate
pre-commit run --all-files

pre-commit-uv swaps pre-commit's own venv creation with uv — hooks run in milliseconds.

Layout

platform/
├── pyproject.toml          # workspace root
├── uv.lock                 # ONE lockfile
├── .python-version
├── apps/
│   ├── api/                # FastAPI service
│   │   ├── pyproject.toml
│   │   └── src/api/
│   ├── worker/             # Celery worker
│   │   ├── pyproject.toml
│   │   └── src/worker/
│   └── cli/                # operator CLI
│       ├── pyproject.toml
│       └── src/cli/
└── libs/
    ├── core/               # domain
    ├── adapters/           # IO ports
    └── observability/      # otel, logging

[tool.uv.sources] — the override table

[project]
dependencies = [
  "internal-utils",
  "shared-models",
  "experimental-fork",
]

[tool.uv.sources]
# local path, editable
internal-utils = {
  path = "../internal-utils",
  editable = true
}

# git, specific branch
shared-models = {
  git = "https://github.com/acme/shared-models",
  branch = "main",
}

# git, exact commit (reproducible!)
experimental-fork = {
  git = "https://github.com/acme/transformers-fork",
  rev = "a1b2c3d4",
}

Declare an extra index

[[tool.uv.index]]
name     = "internal"
url      = "https://pkg.acme.com/simple"
priority = "supplemental"   # only when name not on PyPI
explicit = true             # never search unless asked

[tool.uv.sources]
acme-core = { index = "internal" }

The reproducibility checklist

• Commit pyproject.toml + uv.lock + .python-version
• Use uv sync --frozen in CI and Docker
• Pin uv itself: UV_VERSION=0.5.4 + setup-uv@v3 with: version: 0.5.4
• Pin git sources to a SHA, never a branch
• Pin Docker base images by digest in production

A scripts/ directory in your monorepo

scripts/
├── backfill_users.py
├── replay_kafka.py
├── refresh_secrets.py
└── on_call_dashboard.py

Every file is a self-contained PEP 723 script with its own deps. No shared pyproject.toml. Operators can run any of them on a fresh box with one curl + one chmod.

Project-scoped Jupyter

# add jupyter to a dev group
uv add --group dev jupyterlab ipykernel

# launch in the project env
uv run jupyter lab

# or register a named kernel
uv run python -m ipykernel install \
  --user --name myproj \
  --display-name "Python (myproj)"

Now VS Code, PyCharm, and Jupyter all see "Python (myproj)" pointing at .venv/bin/python.

The classic problem

PyTorch ships different wheels per CUDA version on a separate index — and macOS users want the CPU/MPS wheel from PyPI, not from download.pytorch.org.

uv solves this declaratively in [tool.uv.sources].

When you can't escape conda

Geoscience, bioinformatics, and some CUDA stacks pull non-Python deps (GDAL, samtools, NCCL) that only conda packages cleanly. You can still let uv manage the Python packages on top.

Real-world example: a 110-package web service

Numbers vary; the shape doesn't. uv collapses cold + warm into the same order of magnitude.

Inspect

uv cache dir
# /home/me/.cache/uv

du -sh "$(uv cache dir)"
# 14G   /home/me/.cache/uv

# what's hogging space?
du -h "$(uv cache dir)"/wheels/* \
  | sort -h | tail

Day 1 — Shadow run

1. Install uv on every dev machine and CI runner
2. Add a CI job: uv pip compile pyproject.toml -o /tmp/req.txt — purely informational, doesn't change behaviour
3. Confirm uv produces a workable resolution against current Poetry constraints

"Resolution failed because…"

• uv prints a human-readable conflict tree — read the chain
• Re-run with uv lock -v for the resolver trace
• uv tree + uv tree --invert --package X shows who pulls X

uv tree --depth 2
uv tree --invert --package httpx
uv tree --outdated

What we covered

• Production Dockerfile patterns — single-stage, distroless, multi-stage
• BuildKit cache mounts, dev compose with named-volume venv
• GitHub Actions / GitLab CI / Jenkins / Buildkite recipes
• pre-commit with pre-commit-uv + lock-drift hooks
• Realistic monorepo workspace
• Local / git / private-index dependencies
• Reproducibility, supply-chain hashes, SBOM
• PEP 723 scripts at scale
• PyTorch + CUDA wheel selection
• conda / mamba interop, pixi as alternative
• Migration playbook from Poetry — day-by-day
• Troubleshooting recipes & production cheat sheet