Uv Package Manager

Iron Law

ALWAYS USE uv sync --frozen IN CI AND DOCKER — never uv sync without --frozen in reproducible environments; without it, dependency resolution runs fresh and can pick up different versions

uv Package Manager

Deep reference for uv — the ultra-fast Python package manager written in Rust. The workspace uses uv as its primary Python package manager. This skill covers everything beyond the 4 basic commands in python-dev.

When to Use

Load this skill when:

• Setting up lockfile workflows (uv lock, uv sync --frozen)
• Managing Python version pinning (uv python pin 3.14)
• Configuring Docker builds with uv cache mounts
• Setting up GitHub Actions CI with uv dependency caching
• Working in a monorepo with multiple Python packages
• Migrating an existing project from pip, Poetry, or pip-tools
• Using uv run to execute scripts without environment activation

The python-dev skill covers: uv init, uv add, basic virtual environment setup. Load THIS skill for everything beyond that.

Quick Reference

Reference File

Load resources/implementation-playbook.md for:

• 22 patterns covering all uv workflows
• Virtual environment management (create, activate, uv run)
• Python version management
• Lockfile workflows for reproducible builds
• Monorepo workspace configuration
• Docker multi-stage builds with uv cache mounts
• GitHub Actions CI with uv caching
• Migration guides from pip, Poetry, pip-tools (command-by-command)
• Performance optimization (global cache, parallel install, offline mode)
• Pre-commit hooks and VS Code integration

Key Patterns Summary

# New project (from python-dev)
uv init my-service && cd my-service
uv add fastapi uvicorn pydantic pydantic-settings
uv add --dev pytest pytest-asyncio httpx ruff mypy

# Lockfile (add to CI and Docker)
uv lock                          # Generate/update uv.lock
uv sync --frozen                 # Install exact versions from lock

# Python version
uv python pin 3.14               # Write .python-version file
uv python install 3.14           # Install that version

# Run without activating venv
uv run pytest                    # Run pytest
uv run uvicorn src.main:app      # Run server

Docker Pattern (summary — full pattern in playbook)

FROM python:3.14-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev

CI Pattern (summary — full pattern in playbook)

- uses: astral-sh/setup-uv@v4
  with:
    enable-cache: true
- run: uv sync --frozen