---

name: uv-package-manager description: Comprehensive uv workflows for Python 3.14 — virtual environments, lockfiles, Python version pinning, monorepo workspaces, Docker integration, CI/CD caching, and migration from pip/Poetry/pip-tools. Use when working with uv beyond basic uv add/uv init. allowed-tools: Read, Write, Edit, Bash metadata: triggers: uv package manager, uv lock, uv sync, uv python, uv workspace, uv Docker, uv CI, uv cache, migrate from pip to uv, migrate from poetry to uv, uv monorepo, uv lockfile, uv run related-skills: python-dev, python-packaging, docker domain: backend role: specialist scope: tooling output-format: code last-reviewed: "2026-03-14"

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

Task	Command
Create lockfile	uv lock
Install from lockfile (CI)	uv sync --frozen
Pin Python version	uv python pin 3.14
Run without activating	uv run python script.py
Run tests	uv run pytest
Upgrade all deps	uv lock --upgrade
Check outdated	uv tree --outdated
Remove package	uv remove <pkg>

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