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 ...