Uv

uv: Python Package & Project Manager

uv (v0.11.11, May 2026) replaces pip, pip-tools, pipx, pyenv, virtualenv, and poetry. Written in Rust, 10-100x faster than alternatives. It is stable production software; minor versions can contain breaking changes, while patch releases are intended to be non-breaking.

Workflow Decision Tree

What are you doing?
├─ Running a standalone script? ──────────────────── Scripts workflow
│  (single .py file, no project context needed)
├─ Working in a project with pyproject.toml? ─────── Projects workflow
│  (adding deps, running commands, building)
├─ Running a CLI tool (ruff, ty, pytest)? ────────── Tools workflow
│  (one-off execution, not project-scoped)
├─ Managing Python versions? ─────────────────────── Python workflow
│  (installing, pinning, upgrading interpreters)
├─ Legacy requirements.txt workflow? ─────────────── Pip interface
│  (no pyproject.toml, existing req files)
└─ Building/publishing a package? ────────────────── Build/Publish workflow
   (sdist, wheel, PyPI upload)

Critical rule: If pyproject.toml exists, use project commands (uv add, uv sync, uv run). Never uv pip install in a project, it bypasses the lockfile.

Projects

Initialization

uv init                              # App (main.py, no build system)
uv init --lib                        # Library (src/ layout, uv_build backend, py.typed)
uv init --package                    # Packaged app (src/ layout, entry points)
uv init --build-backend uv_build     # Explicit backend choice
uv init --build-backend maturin      # Rust extension module
uv init --python 3.13                # Specific Python version
uv init --bare                       # pyproject.toml only

Dependency Management

uv add httpx                         # Add to project.dependencies
uv add httpx --dev                   # Add to dependency-groups.dev
uv add httpx --group lint            # Add to dependency-groups.lint
uv add httpx --optional network      # Add to project.optional-dependencies.network
uv add -r requirements.txt           # Import from requirements file
uv remove httpx                      # Remove dependency

# Version bounds (configurable default via add-bounds setting)
uv add 'httpx>=0.27'                 # Lower bound (default behavior)
uv add 'httpx~=0.27.0'              # Compatible release

Dependency Groups (PEP 735)

[dependency-groups]
dev = ["pytest>=8", "ruff"]
lint = ["ruff"]
test = ["pytest", {include-group = "lint"}]  # Nest groups

[tool.uv]
default-groups = ["dev", "lint"]  # Synced by default

Sync & Run

uv sync                              # Install from lockfile
uv sync --locked                     # Error if lockfile stale (use in CI)
uv sync --frozen                     # Use lockfile as-is, no update
uv sync --no-dev                     # Skip dev dependencies
uv sync --all-extras                 # All optional dependencies
uv sync --all-groups                 # All dependency groups
uv sync --group lint                 # Include specific group
uv sync --no-install-project         # Deps only (Docker layer caching)
uv sync --inexact                    # Don't remove extraneous packages

uv run pytest                        # Run in project environment
uv run --with hypothesis pytest      # Ad-hoc extra dependency
uv run -p 3.12 pytest                # Specific Python version

Locking

uv lock                              # Resolve and lock dependencies
uv lock --upgrade                    # Upgrade all to latest compatible
uv lock --upgrade-package httpx      # Upgrade specific package
uv lock --check                      # Verify lockfile current (CI)
uv lock --resolution lowest          # Minimum compatible versions

Export

uv export --format requirements-txt  # requirements.txt
uv export --format pylock-toml       # PEP 751 (preview)

Scripts (PEP 723)

Single-file scripts with inline dependency metadata. Scripts with metadata run in complete isolation, project dependencies are ignored even inside a project directory.

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx", "rich>=13"]
# [tool.uv]
# exclude-newer = "2026-03-01T00:00:00Z"
# ///

import httpx

uv run script.py                     # Run with inline deps
uv add --script script.py 'click'    # Add dep to script metadata
uv lock --script script.py           # Create script.py.lock
uv init --script example.py          # Create script with metadata template
echo 'print("hi")' | uv run -       # Read from stdin

Tools

uvx ruff check .                     # Run tool in isolated env
uvx ruff@0.15.12 check .            # Specific version
uvx --from 'httpie' http             # Package name differs from command
uvx --python 3.12 ruff              # With specific Python

uv tool install ruff                 # Persistent install to PATH
uv tool upgrade --all                # Upgrade all installed tools
uv tool list --outdated              # Show available updates (0.10.10+)

Key distinction: uvx creates isolated environments, tools are CLI-only, not importable. For tools needing project context (pytest, mypy), use uv run inside a project.

Python Management

uv python install 3.13               # Install latest patch
uv python install 3.13t              # Free-threaded (no GIL)
uv python install pypy               # PyPy implementation
uv python upgrade 3.13               # Upgrade to latest patch (0.10.0+)
uv python pin 3.13                   # Create .python-version
uv python list --only-installed      # Show installed versions

Workspaces

# Root pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]
exclude = ["packages/experimental"]

[tool.uv.sources]
my-lib = { workspace = true }

Key behaviors:

• Single lockfile across all members
• Single `requires-python`: intersection of all members
• Workspace members are always editable
• Root tool.uv.sources apply to all members unless overridden
• Config in uv.toml is read only from workspace root, member-level config is ignored

uv workspace dir                     # Print workspace root
uv workspace list                    # List members
uv run --package my-lib pytest       # Run in specific member context
uv build --package my-lib            # Build specific member

Virtual workspaces (no root package):

[tool.uv]
package = false

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

Publishing

uv version                           # Read current version
uv version --bump minor              # 1.0.0 -> 1.1.0
uv version --bump patch --dry-run    # Preview change
uv build                             # Build sdist + wheel
uv build --list                      # Preview included files
uv publish                           # Publish to PyPI
uv publish --token pypi-xxx          # With API token
uv publish --index testpypi          # Custom registry
uv publish --check-url https://pypi.org/simple/  # Skip if exists

Trusted publishing (GitHub Actions, no credentials):

permissions:
  id-token: write
steps:
  - run: uv build && uv publish

Preview Features (0.10+)

Enable with --preview or UV_PREVIEW=1, or selectively with --preview-features:

uv audit --preview                   # Scan for vulnerabilities

Configuration Quick Reference

Precedence: CLI flags > env vars > project uv.toml > project pyproject.toml [tool.uv] > user ~/.config/uv/uv.toml > system /etc/uv/uv.toml

In a workspace, config search starts at workspace root. uv.toml takes precedence over pyproject.toml in the same directory.

.env file support: uv run automatically loads .env files. Control with --env-file or UV_NO_ENV_FILE=1.

For full configuration reference, see references/configuration.md. For Docker and CI/CD patterns, see references/docker-ci.md. For dependency resolution deep dive, see references/resolution.md.

Non-Obvious Gotchas

Anti-Patterns

What This Skill is NOT

• Not a replacement for reading uv --help for flag discovery
• Not for Poetry/PDM projects (those have their own lock formats)
• Not for building C/Rust extensions (see uv-build skill for backend limitations)
• Not for ruff/ty configuration (see dedicated ruff and ty skills)

uv Configuration Reference

File Locations

uv.toml takes precedence over pyproject.toml in the same directory. In workspaces, only workspace root config is read.

All Settings

Project Settings

Resolution Settings

Installation Settings

Python Settings

Index Settings

Preview Settings

Critical Environment Variables

Example: Complete Project Config

[tool.uv]
required-version = ">=0.11"
python-preference = "managed"
compile-bytecode = true
add-bounds = "lower"
default-groups = ["dev", "lint"]
fork-strategy = "requires-python"

[[tool.uv.index]]
name = "internal"
url = "https://pypi.internal.com/simple/"
default = true

[tool.uv.sources]
my-lib = { workspace = true }
torch = { index = "pytorch-cpu" }

Example: uv.toml (Standalone)

# No [tool.uv] prefix — top-level keys
required-version = ">=0.11"
python-preference = "managed"
compile-bytecode = true

[[index]]
name = "internal"
url = "https://pypi.internal.com/simple/"

[pip]
index-url = "https://pypi.org/simple"

Docker & CI/CD Patterns for uv

Docker — Optimized Multi-Stage Build

FROM python:3.13-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:0.11.7 /uv /uvx /bin/

ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy

WORKDIR /app

# Layer 1: Install deps only (cached unless lock changes)
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project --no-editable

# Layer 2: Install project code
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-editable

# Final stage: just the venv
FROM python:3.13-slim
COPY --from=builder /app/.venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH"
CMD ["my_app"]

Docker Environment Variables

Docker Tips

• Add .venv to .dockerignore — prevents local environments from being copied
• Use --no-editable in production images — avoids .pth file overhead
• The --mount=type=bind pattern avoids COPY for lock/pyproject — better cache hits
• For workspace builds, bind the entire workspace root

Hardened Images (0.10.8+)

Astral publishes hardened Docker images with SBOM attestations:

FROM ghcr.io/astral-sh/uv:0.11.7  # Full image with uv
FROM ghcr.io/astral-sh/uv:0.11.7-python3.13-bookworm  # With Python

GitHub Actions

Basic Test Matrix

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.11", "3.12", "3.13"]
    steps:
      - uses: actions/checkout@v6
      - uses: astral-sh/setup-uv@v7
        with:
          python-version: ${{ matrix.python-version }}
          enable-cache: true
      - run: uv sync --locked --all-extras --all-groups
      - run: uv run pytest tests

Lockfile Verification

- run: uv lock --check # Fails if lockfile is stale

Trusted Publishing (No Credentials)

name: Publish
on:
  push:
    tags: [v*]
jobs:
  publish:
    runs-on: ubuntu-latest
    environment: pypi
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v6
      - uses: astral-sh/setup-uv@v7
      - run: uv python install 3.13
      - run: uv build
      - run: uv publish

PEP 740 attestations are discovered and uploaded automatically. Use --no-attestations if a registry rejects them.

Pre-commit Integration

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.11.7
    hooks:
      - id: uv-lock # Keep uv.lock in sync
      - id: uv-export # Keep requirements.txt in sync

PyTorch Configuration

Automatic GPU Detection

uv pip install torch --torch-backend=auto    # Detects CUDA/ROCm/CPU
UV_TORCH_BACKEND=cu128 uv sync              # Explicit backend

Project-Level Per-Platform Config

[tool.uv.sources]
torch = [
  { index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
  { index = "pytorch-cu128", marker = "sys_platform == 'linux'" },
]

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[[tool.uv.index]]
name = "pytorch-cu128"
url = "https://download.pytorch.org/whl/cu128"
explicit = true

Conflict-Based Extras (Recommended)

[project.optional-dependencies]
cpu = ["torch>=2.9.1"]
cu128 = ["torch>=2.9.1"]

[tool.uv]
conflicts = [[{extra = "cpu"}, {extra = "cu128"}]]

[tool.uv.sources]
torch = [
  { index = "pytorch-cpu", extra = "cpu" },
  { index = "pytorch-cu128", extra = "cu128" },
]

Install with: uv sync --extra cu128

Dependency Resolution Deep Dive

Resolution Strategies

Universal vs Platform-Specific

Universal (uv.lock, default): Portable across all platforms and Python versions. Lists packages multiple times with different versions per platform via fork markers.

Platform-specific (uv pip compile): Resolves for current platform only. Cross-compile with --python-platform and --python-version.

Fork Strategy

[tool.uv]
fork-strategy = "requires-python"  # Default: latest per Python version
# fork-strategy = "fewest"         # Minimize version count across platforms

Environment Constraints

[tool.uv]
# Narrow resolution to these platforms only
environments = ["sys_platform == 'darwin'", "sys_platform == 'linux'"]

# REQUIRE wheels to exist for these (fail if missing)
required-environments = ["sys_platform == 'linux' and platform_machine == 'aarch64'"]

Overrides vs Constraints

[tool.uv]
override-dependencies = ["numpy>=1.24,<2"]      # Force version range
constraint-dependencies = ["requests>=2.28"]     # Floor only

Use overrides when a transitive dependency declares an incorrect upper bound. Use constraints to enforce minimum versions globally.

Dependency Metadata (Skip Source Builds)

[[tool.uv.dependency-metadata]]
name = "chumpy"
version = "0.70"
requires-dist = ["numpy>=1.8.1", "scipy>=0.13.0"]

Provides static metadata without building source distributions — useful for packages with exotic build requirements (CUDA, Fortran, etc.).

Conflict Declaration

[tool.uv]
conflicts = [
  [
    { extra = "cpu" },
    { extra = "gpu" },
  ]
]

Tells the resolver these extras are mutually exclusive — prevents impossible resolution.

Reproducibility

[tool.uv]
exclude-newer = "2026-03-01T00:00:00Z"   # RFC 3339 timestamp
exclude-newer = "30 days"                  # Relative duration
exclude-newer = "PT24H"                    # ISO 8601 duration

Per-package: exclude-newer-package setting.

Pre-release Handling

Pre-releases accepted only when:

1. Directly specified with pre-release qualifier (e.g., flask>=2.0.0rc1) 2. All published versions are pre-releases 3. --prerelease allow flag used

Sources

[tool.uv.sources]
# Workspace member
my-lib = { workspace = true }

# Git (tag, branch, or rev)
httpx = { git = "https://github.com/encode/httpx", tag = "0.27.0" }
langchain = { git = "https://github.com/langchain-ai/langchain", subdirectory = "libs/langchain" }

# Local path (editable or not)
my-lib = { path = "../libs/my-lib", editable = true }

# URL
httpx = { url = "https://example.com/httpx-0.27.0.tar.gz" }

# Index (explicit registry)
torch = { index = "pytorch" }

# Platform-specific sources
httpx = [
  { git = "https://github.com/encode/httpx", tag = "0.27.2", marker = "sys_platform == 'darwin'" },
  { git = "https://github.com/encode/httpx", tag = "0.24.1", marker = "sys_platform == 'linux'" },
]

`tool.uv.sources` are development-only. They are stripped when building (uv build --no-sources) and publishing. Published packages only see project.dependencies.

Index Configuration

[[tool.uv.index]]
name = "internal"
url = "https://pypi.internal.com/simple/"
default = true          # Use as default instead of PyPI

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
explicit = true         # Only used when explicitly referenced in sources

`index-strategy` controls multi-index search:

• first-index (default): Use first index that has the package
• unsafe-first-match: Search all indexes, use first match
• unsafe-best-match: Search all indexes, use best version

Lockfile Schema

• TOML format, schema-versioned by minor uv releases
• revision field tracks backwards-compatible changes
• uv rejects lockfiles with newer schema versions — pin required-version to avoid surprises