89jobrien Python UV Package Management
Core Principle
UV is the modern standard for Python dependency management. It provides deterministic resolution, 10-100x speed improvement over pip, and built-in virtual environment management.
When to Use This Skill
- Setting up new Python projects
- Managing Python dependencies
- Running
.pyfiles and commands - Running python tools like
pytestandruff - Creating Dockerfiles for Python applications
- CI/CD pipelines for Python
- Migrating from pip/poetry to UV
Why UV Over Alternatives
Speed comparison (20 dependencies, cold install):
- pip install: 120-180 seconds
- uv sync: 15-20 seconds (10x faster)
With cache:
- pip install (cached): 60-90 seconds
- uv sync (cached): 2-5 seconds (30x faster)
Additional benefits:
- Deterministic resolution (lockfile guarantees exact versions)
- Built-in virtual environment management
- Docker cache-friendly (separate download/install phases)
- Drop-in pip compatibility
- Cross-platform lockfiles
Standard Workflow
Project Setup
# Initialize new project (creates pyproject.toml)
uv init
# Or add UV to existing project with pyproject.toml
uv lock # Generate uv.lock from pyproject.toml
Daily Development
# Install all dependencies (creates/updates venv)
uv sync
# Install without dev dependencies
uv sync --no-dev
# Add runtime dependency
uv add boto3>=1.40.0
# Add dev dependency
uv add --dev pytest>=8.0.0
# Remove dependency
uv remove boto3
# Update lockfile (resolve latest within constraints)
uv lock --upgrade
# Run command in virtual environment
uv run pytest tests/
uv run python -m myapp
uv run mypy src/
Lockfile Management
# Generate/update lockfile
uv lock
# Update all dependencies to latest (within constraints)
uv lock --upgrade
# Update specific package
uv lock --upgrade-package boto3
# Verify lockfile is in sync (CI check)
uv lock --check
Docker Integration Pattern
Standard Dockerfile Structure
FROM python:3.12-slim AS builder
WORKDIR /app
# Copy UV from official image (always current)
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
# Copy dependency files FIRST (layer caching)
COPY pyproject.toml uv.lock ./
# Install with cache mount (fast rebuilds)
RUN --mount=type=cache,target=/root/.cache/uv,sharing=locked \
uv sync --frozen
# Copy source code AFTER dependencies (cache-friendly)
COPY src/ ./src/
# ... rest of build
The --frozen Discipline
CRITICAL: Different flags for different contexts
Development (local):
uv sync # May update uv.lock if out of sync
CI/Docker (production):
uv sync --frozen # FAILS if uv.lock doesn't match pyproject.toml
Why --frozen in Docker/CI:
- Ensures lockfile is committed and current
- Prevents silent dependency changes during build
- Build failure = lockfile drift (intentional safety)
- Reproducible builds guaranteed
Multi-Stage with UV
# STAGE 1: Builder (with dev deps for testing)
FROM python:3.12-slim AS builder
WORKDIR /app
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
# Install ALL dependencies (including dev)
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv,sharing=locked \
uv sync --frozen
# Copy source and tests
COPY src/ ./src/
COPY tests/ ./tests/
# Run tests during build
RUN uv run pytest tests/
# Build wheel
RUN uv build
# STAGE 2: Runtime (production deps only)
FROM python:3.12-slim
WORKDIR /app
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
# Install ONLY runtime dependencies
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv,sharing=locked \
uv sync --frozen --no-dev --no-install-project
# Install built wheel from builder
COPY --from=builder /app/dist/*.whl ./
RUN uv pip install *.whl && rm *.whl
ENV PATH="/app/.venv/bin:$PATH"
ENTRYPOINT ["python", "-m", "myapp"]
pyproject.toml Structure
[project]
name = "myproject"
version = "0.1.0"
description = "Project description"
requires-python = ">=3.12"
dependencies = [
"boto3~=1.40.52", # Runtime deps
"pydantic>=2.0.0,<3.0.0",
]
[project.optional-dependencies]
dev = [
"pytest>=8.0.0", # Dev/test deps
"mypy>=1.8.0",
"ruff>=0.1.0",
]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.uv]
# UV-specific configuration (optional)
Decision Framework
Q: When should I use pip instead of UV?
A: Rarely. UV handles all pip use cases faster.
Exception: Legacy systems that can't install UV.
Q: How do I migrate from pip/requirements.txt?
A: 1. Create pyproject.toml with dependencies
2. Run: uv lock
3. Run: uv sync
4. Delete requirements.txt
Q: How do I migrate from poetry?
A: 1. UV reads pyproject.toml (poetry format compatible)
2. Run: uv lock (generates uv.lock)
3. Run: uv sync
4. Optionally remove poetry.lock
Q: When to use uv sync vs uv sync --frozen?
A: Development: uv sync (flexible)
CI/Docker: uv sync --frozen (strict)
Q: How to handle private packages?
A: uv add package --index-url https://private.pypi/simple/
Or configure in pyproject.toml [tool.uv.sources]
CI/CD Patterns
GitHub Actions
- name: Install UV
uses: astral-sh/setup-uv@v1
- name: Install dependencies
run: uv sync --frozen
- name: Run tests
run: uv run pytest tests/
- name: Type check
run: uv run mypy src/
Pre-commit Hook
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: uv-lock-check
name: Check uv.lock is in sync
entry: uv lock --check
language: system
pass_filenames: false
Anti-Patterns
❌ Using pip for new Python projects
→ UV is faster and more reliable
❌ Not using --frozen in Docker/CI
→ Silent dependency drift, unreproducible builds
❌ Committing without uv.lock
→ Loses reproducibility, different installs per machine
❌ Manual venv management (python -m venv)
→ UV handles this automatically
❌ Using requirements.txt with UV
→ Use pyproject.toml (modern standard)
❌ Ignoring uv.lock in .gitignore
→ Lockfile MUST be committed for reproducibility
✅ `uv` for all Python dependency management
✅ --frozen in all CI/Docker contexts
✅ Commit uv.lock alongside pyproject.toml
✅ Let UV manage virtual environments
✅ Use cache mounts in Docker for speed
Integration with Other Skills
- version-pinning: Use for constraint strategy (~= vs >=)
- docker-multistage: UV integrates with multi-stage pattern
- version-currency: uv.lock is authoritative for version verification
- container-boundary: UV venv is container-local, not host
Lockfile as Source of Truth
The uv.lock file contains:
- Exact version of every dependency (including transitive)
- SHA256 hashes for integrity verification
- Source URLs for each package
- Platform-specific resolutions
This provides:
- Reproducible builds across machines/time
- Security via tamper detection (hashes)
- Auditability (know exactly what's installed)
- Version verification (see version-currency skill)
Meta-Principle
UV modernizes Python dependency management.
Old way (pip):
- Slow installs
- Non-deterministic resolution
- Manual venv management
- requirements.txt (limited metadata)
New way (UV):
- Fast installs (10-100x)
- Deterministic resolution (lockfile)
- Automatic venv management
- pyproject.toml (rich metadata)
For any new Python project: Start with UV.
For existing projects: Migrate to UV.
The --frozen flag is your CI/Docker safety net.
Never ship without it.