uv Docker Production: AI-Optimized Technical Reference

Configuration - Critical Environment Variables

Required Docker Environment Variables:

ENV UV_LINK_MODE=copy \
    UV_COMPILE_BYTECODE=1 \
    UV_PYTHON_DOWNLOADS=never \
    UV_PYTHON=python3.12 \
    UV_PROJECT_ENVIRONMENT=/app \
    UV_CACHE_DIR=/tmp/uv-cache

Critical Failure Mode: UV_LINK_MODE=copy is mandatory - Docker filesystems don't support hard links, causing silent failures without this setting.

Performance Impact: UV_COMPILE_BYTECODE=1 provides noticeably faster startup times in production containers.

Performance Benchmarks

Metric	pip + venv	Poetry	uv
First Build Time	8-12 minutes	6-10 minutes	2-4 minutes
Cached Build Time	3-5 minutes	2-4 minutes	15-45 seconds
Final Image Size	450-600 MB	500-700 MB	200-350 MB
Memory Usage (Build)	1-2 GB	1.5-3 GB	1-2 GB

Real-world Impact: Production builds reduced from 12+ minutes to 3 minutes with proper Docker layer caching.

Resource Requirements

Minimum Memory Limits:

• Build containers: 2GB minimum (prevents OOM kills during parallel dependency resolution)
• Production runtime: Standard Python memory requirements

Memory Spike Mitigation:

ENV UV_CONCURRENT_DOWNLOADS=1
ENV UV_RESOLUTION_MEMORY_LIMIT=1GB

Cache Performance Requirements:

• Cache mount location must exist: --mount=type=cache,target=/root/.cache/uv
• Cache mount reduces build time from 8 minutes to 2 minutes after first build

Critical Warnings - Production Failure Modes

Build Context Failures

Symptom: "COPY failed: no such file or directory"
Root Cause: uv.lock or pyproject.toml not in Docker build context
Solution: Move Dockerfile to project root OR configure .dockerignore correctly

Permission Denied Errors

Symptom: "PermissionError: [Errno 13] Permission denied" during uv sync
Root Causes:

1. Build stage runs as root, runtime as non-root user
2. System Python packages directory is read-only

Solutions:

• Use COPY --chown=user:user /app /app for proper ownership
• Set UV_PROJECT_ENVIRONMENT=/app for writable location

Memory-Related Build Failures

Symptom: OOMKilled during dependency installation
Root Cause: uv's parallel dependency resolution spikes memory usage in containerized environments
Frequency: Common in containers with memory limits under 2GB

Alpine Linux Compatibility Issues

Critical Warning: Don't use Alpine for Python applications
Impact: musl libc causes compatibility issues with many Python packages
Time Cost: Can require 3+ days debugging numpy imports and compilation issues
Alternative: Use debian-slim or ubuntu (50MB size difference is not worth compatibility problems)

Multi-Stage Build Pattern - Production Template

Dependency Installation Order (Critical for Caching):

1. Copy ONLY uv.lock and pyproject.toml
2. Run uv sync (this layer caches until lock file changes)
3. Copy application source code

Failure Mode: If source code is copied first, every code change invalidates dependency cache.

# Stage 1: Dependencies only
FROM python:3.12-slim AS deps
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

ENV UV_LINK_MODE=copy UV_COMPILE_BYTECODE=1 UV_PYTHON_DOWNLOADS=never

WORKDIR /app
RUN --mount=type=cache,target=/root/.cache \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-dev --no-install-project

# Stage 2: Application code
COPY . /src
WORKDIR /src
RUN --mount=type=cache,target=/root/.cache \
    uv sync --locked --no-dev --no-editable

# Stage 3: Production runtime
FROM python:3.12-slim
COPY --from=deps /app /app
ENV PATH=/app/bin:$PATH
USER 1001
WORKDIR /app

Common Production Failures - Troubleshooting Guide

"uv command not found" in runtime

Cause: uv copied to build stage but not runtime stage
Solution: Don't copy uv to runtime - only copy built virtual environment

"Package not found" for existing packages

Causes:

• Private PyPI authentication not configured in container
• Corporate proxy/SSL certificate issues
• Network timeout in restrictive environments

Solutions:

ENV REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
ENV UV_HTTP_TIMEOUT=300
ENV UV_EXTRA_INDEX_URL=https://your-private-pypi.com/simple/

Build Cache Not Working

Symptom: Rebuilds all dependencies on every code change
Root Cause: Incorrect layer ordering in Dockerfile
Impact: Increases build time from 45 seconds to 3+ minutes

Container Size Bloat (2GB+ images)

Causes:

• Build tools included in runtime image
• Copying unnecessary files (.git, pycache)
• Not using multi-stage builds properly

Solutions:

• Use .dockerignore to exclude development files
• Runtime stage should only include Python runtime and dependencies
• Multi-stage builds can reduce image size by 70-90%

Security Configuration

Non-root Execution Pattern:

RUN groupadd -r appuser && useradd -r -g appuser appuser
COPY --from=build --chown=appuser:appuser /app /app
USER appuser

Secret Management (Private Repositories):

RUN --mount=type=secret,id=pip_index_url \
    UV_EXTRA_INDEX_URL=$(cat /run/secrets/pip_index_url) \
    uv sync --locked

Critical Security Warning: Never put authentication tokens directly in Dockerfile - they persist in image layers permanently.

CI/CD Integration Requirements

Cache Strategy for GitHub Actions:

cache-from: type=gha
cache-to: type=gha,mode=max

Container Testing (Essential):

• Always test container actually starts and imports work
• Include smoke tests to catch 90% of container issues before deployment
• Monitor cold start times and memory usage patterns

Build Dependencies for CI:

RUN apt-get update && apt-get install -y \
    build-essential \
    python3.X-dev \
    libffi-dev \
    libssl-dev

Monitoring and Operational Intelligence

Expected Container Metrics:

• Production containers: ~200MB (if significantly larger, build tools included in runtime)
• Cold start time: Noticeably faster with UV_COMPILE_BYTECODE=1
• Memory usage: Lower than pip equivalents due to better dependency resolution

Disk Space Management:

• uv cache can grow large in production environments
• Monitor and periodically clean /tmp/uv-cache
• Corporate networks may require increased timeout settings

Health Check Pattern:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python -c "import your_app; print('OK')" || exit 1

Decision Support Information

When to Use uv in Docker:

• Build time reduction from 12+ minutes to 3 minutes justifies adoption
• Deterministic dependency resolution improves Docker layer caching effectiveness
• Worth migration cost despite initial configuration complexity

Trade-offs:

• Benefit: Significantly faster builds and smaller images
• Cost: Initial learning curve for Docker-specific configuration
• Hidden Cost: Debugging containerization issues requires understanding uv-specific behaviors

Migration Difficulty: Easier than Poetry containerization, harder than simple pip requirements.txt

Prerequisites:

• Understanding of multi-stage Docker builds
• Knowledge of Docker layer caching strategies
• Experience with Python virtual environments in containers