---

name: uv description: uv workflows for Python — dependencies, virtualenvs, PEP 723 scripts, Python version management, CI, and Docker. Use when working on Python packaging/deps/tooling, writing GitHub Actions for Python projects, or building Docker images for Python apps.

uv Field Manual

Assumption: uv is installed and on PATH (uv --version to confirm; if missing, halt and report). Version pins below were current 2026-07-05 — verify before relying on them.

Daily workflows

Project ("cargo-style") flow

uv init myproj                     # create pyproject.toml + .venv
cd myproj
uv add ruff pytest httpx           # fast resolver + lock update
uv run pytest -q                   # run tests in project venv
uv lock                            # refresh uv.lock (if needed)
uv sync --locked                   # reproducible install (CI-safe)

Script flow (PEP 723)

uv run hello.py                    # zero-dep script, auto-env
uv add --script hello.py rich      # embeds dep metadata in the script
uv run --with rich hello.py        # transient deps, no state

CLI tools (pipx replacement)

uvx ruff check .                   # ephemeral run
uv tool install ruff               # user-wide persistent install
uv tool list                       # audit installed CLIs
uv tool update --all               # keep them fresh

Python version management

uv python install 3.12 3.13
uv python pin 3.13                 # writes .python-version
uv run --python 3.12 script.py

Legacy pip interface

uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt
uv pip sync   -r requirements.txt   # deterministic install

Performance knobs

| Env Var | Purpose | Typical value | | ------------------------- | ----------------------- | ------------- | | UV_CONCURRENT_DOWNLOADS | saturate fat pipes | 16 or 32 | | UV_CONCURRENT_INSTALLS | parallel wheel installs | CPU cores | | UV_OFFLINE | cache-only mode | 1 | | UV_INDEX_URL | internal mirror | https://… | | UV_PYTHON | pin interpreter in CI | 3.13 |

uv cache dir && uv cache size      # show path + size
uv cache clean                     # wipe wheels & sources

CI: GitHub Actions

name: tests
on: [push]
jobs:
  pytest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v8.2.0   # immutable releases since v8.0.0 — moving tags like @v8 do NOT exist; pin the full version
      - run: uv python install            # obeys .python-version
      - run: uv sync --locked
      - run: uv run pytest -q

Docker (multistage — the one true recipe)

# Build stage
FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim AS builder
WORKDIR /app
# Deps first for layer caching; code after
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-cache --no-dev

# Runtime stage
FROM debian:bookworm-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
RUN useradd --create-home --shell /bin/bash app
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY --chown=app:app . .
USER app
ENV PATH="/app/.venv/bin:$PATH"
CMD ["uv", "run", "python", "-m", "myapp"]

Tips: copy pyproject.toml + uv.lock before app code (layer caching); --frozen honors the lockfile exactly; --no-cache keeps the image lean; --no-dev skips dev deps; set PATH so the venv is active.

Migration matrix

| Legacy | Replacement | | -------------------- | ---------------------- | | python -m venv | uv venv | | pip install | uv pip install | | pip-tools compile | uv lock | | pipx run | uvx | | poetry add | uv add | | pyenv install | uv python install |

Troubleshooting

| Symptom | Resolution | | ------------------------ | ------------------------------------------------------ | | Python X.Y not found | uv python install X.Y or set UV_PYTHON | | C-extension build errors | unset UV_NO_BUILD_ISOLATION | | Need a fresh env | uv cache clean && rm -rf .venv && uv sync | | Still stuck | RUST_LOG=debug uv ... |