uv Docker Production Deployment - Troubleshooting & Best Practices

I've been running uv in production Docker containers since the early versions. It's fast as hell, but Docker deployment isn't just "replace pip with uv" and call it done. You'll hit edge cases that'll make you question your life choices.

The Docker build process with uv follows a typical multi-stage pattern: dependencies first, then application code, then runtime optimization.

The big win? Our production builds went from 12+ minutes to around 3 minutes. Docker layer caching actually works now because uv's dependency resolution is deterministic. But you need to structure your Dockerfile correctly or you'll lose all those gains.

The Critical Docker Environment Variables

uv behaves differently in containers. These settings will save your ass:

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

UV_LINK_MODE=copy is crucial - Docker filesystems don't support hard links properly, and uv will fail silently without this. Spent a weekend debugging that shit before figuring it out.

UV_COMPILE_BYTECODE=1 gives you faster startup times. Noticeably improved our cold start times.

UV_PYTHON_DOWNLOADS=never prevents uv from trying to download Python builds inside containers. Use the system Python you installed.

Multi-Stage Builds That Actually Work

Docker multi-stage builds follow a pattern: build dependencies in one stage, compile/install in another, then copy only runtime artifacts to the final image. This reduces image size by 70-90% and improves security by excluding build tools from production containers.

Here's the production Dockerfile pattern I use. Note the dependency separation - this is where most people fuck up:

## Stage 1: Build 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: Add 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

The key insight: install dependencies first, then add your application code. This way, dependency layers only rebuild when uv.lock changes, not every time you modify your source.

Production Performance Gotchas

Cache mount location matters. I've seen builds fail because /root/.cache doesn't exist in the container. Use an explicit mount target.

File ownership gets fucked. If your build stage runs as root but runtime uses a different user, you'll get permission denied errors. Took down staging for 2 hours once because I forgot the chown flag. Use COPY --chown=app:app to fix ownership during copy.

Virtual environments in containers are worth it. I know it sounds redundant, but virtualenvs provide isolation and make debugging easier. Plus, uv creates them so fast it doesn't matter.

Real Error You'll Hit: "COPY failed: no such file or directory"

This happens when uv.lock or pyproject.toml isn't in your Docker build context. The fix is either:

1. Move your Dockerfile to the project root
2. Use .dockerignore correctly to include necessary files
3. Or copy the files explicitly in a separate layer first

Don't try to mount them from outside the build context - Docker won't let you.

Memory Limits Will Bite You

uv's parallel dependency resolution can spike memory usage. In containerized environments with memory limits, this causes OOM kills during uv sync.

The fix: UV_CONCURRENT_DOWNLOADS=1 to serialize downloads, or increase your build container memory limits. We run builds with 2GB minimum now.

Private Package Repositories

If you're using private PyPI indexes, Docker secrets mounting works better than environment variables:

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

Don't put authentication tokens directly in the Dockerfile - they end up in the image layers forever.

Essential Docker + uv Resources

• Official uv Docker guide - official documentation for container integration
• uv environment variables reference - complete list of configuration options for containers
• Docker BuildKit documentation - advanced build features and optimizations
• Multi-stage build best practices - Docker's official optimization guidelines
• Docker secrets management - secure handling of sensitive data in builds
• Container memory management - setting resource limits and troubleshooting OOM issues
• Python Docker best practices - comprehensive guide for Python containers
• uv-docker-example repository - official production-ready Dockerfile examples
• Dockerfile linting with hadolint - automated best practices checking for Dockerfiles
• Container security scanning - vulnerability detection for production images
• GitHub Actions Docker integration - CI/CD pipeline setup for container builds
• Production deployment troubleshooting - real-world deployment patterns and common issues

Here's the Dockerfile I actually use in production.

It handles the edge cases I've hit running uv-based containers:

## syntax=docker/dockerfile:
1.9
FROM python:
3.12-slim AS build

SHELL [\"bash\", \"-euxo\", \"pipefail\", \"-c\"]
ENV DEBIAN_FRONTEND=noninteractive

## Install build dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    ca-certificates \
    curl \
    && rm -rf /var/lib/apt/lists/*

## Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

## Configure uv for containers
ENV UV_LINK_MODE=copy \
    UV_COMPILE_BYTECODE=1 \
    UV_PYTHON_DOWNLOADS=never \
    UV_PYTHON=python3.12 \
    UV_PROJECT_ENVIRONMENT=/app

## Create non-root user for runtime
RUN groupadd -r appuser && useradd -r -g appuser appuser

## Install dependencies first (better caching)
WORKDIR /src
COPY uv.lock pyproject.toml ./

RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=cache,target=/root/.cache/pip \
    uv sync --locked --no-dev --no-install-project

## Install application code
COPY . .

RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-dev --no-editable

## Runtime stage
FROM python:
3.12-slim AS runtime

## Runtime dependencies (no build tools)
RUN apt-get update && apt-get install -y \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/* \
    && groupadd -r appuser && useradd -r -g appuser appuser

## Copy virtual environment
COPY --from=build --chown=appuser:appuser /app /app

## Set up environment
ENV PATH=\"/app/bin:$PATH\" \
    PYTHONPATH=\"/app/lib/python3.12/site-packages\" \
    PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1

USER appuser
WORKDIR /app

## Verify installation and run smoke test
RUN python --version && \
    python -m pip list && \
    python -c \"import sys; print(f'Python executable: {sys.executable}')\"

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

EXPOSE 8000
CMD [\"python\", \"-m\", \"your_app\"]

Key Production Patterns

Environment variable layering (this tripped me up initially): I set UV_* variables in the build stage only.

Runtime doesn't need them, which keeps the runtime environment clean.

Cache mounting strategy: Both uv and pip caches are mounted.

This handles cases where uv falls back to pip for problematic packages.

User management: Create the user in both stages.

Some base images handle this differently, causing ownership issues when copying between stages.

Verification step: The smoke test (basic import/startup verification) catches 90% of container issues before deployment.

It's saved my ass more times than I can count.

CI/CD Integration That Works

*CI/CD workflow: Code push triggers automated build, test, and deployment stages.

Container images are built, tested for functionality, scanned for vulnerabilities, then pushed to registry if all checks pass. This ensures reliable, secure deployments.*

Here's the GitHub Actions workflow I use for building and pushing containers:

name:

 Build Container
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:

- uses: actions/checkout@v4
    
    
- name:

 Set up Docker Buildx
      uses: docker/setup-buildx-action@v3
      
    
- name:

 Build and test
      uses: docker/build-push-action@v5
      with:
        context: .
        target: runtime
        cache-from: type=gha
        cache-to: type=gha,mode=max
        load: true
        tags: myapp:test
        
    
- name:

 Test container
      run: |
        docker run --rm myapp:test python -c \"import your_app; print('Import test passed')\"
        docker run --rm -d --name test-container myapp:test
        sleep 5
        docker logs test-container
        docker stop test-container
        
    
- name:

 Push to registry
      if: github.ref == 'refs/heads/main'
      uses: docker/build-push-action@v5
      with:
        context: .
        push: true
        tags: your-registry/myapp:latest

Cache strategy: GitHub Actions cache significantly speeds up builds.

First build usually takes a few minutes, subsequent builds are much faster.

Container testing (learned this the hard way): Always test that the container actually starts and imports work.

I've caught countless issues this way.

Monitoring and Debugging

Container size monitoring: Our production containers are around 200MB.

If yours are way bigger, you're probably including build tools in runtime.

Startup time tracking: We monitor cold start times.

With uv + bytecode compilation, startup got noticeably faster.

Memory usage patterns: uv containers use less memory than pip equivalents because of better dependency resolution.

But monitor for memory leaks in long-running containers.

Security Considerations

Minimal runtime surface: Runtime containers only include Python runtime and application dependencies.

No compilers, package managers, or dev tools.

Non-root execution: All containers run as non-root users.

File permissions are set correctly during the build stage.

Dependency scanning: We scan uv.lock files for vulnerabilities using pip-audit before building containers:

uv tool run pip-audit --requirement uv.lock --format json --output audit.json

Common Production Failures

Disk space issues: uv's cache can grow large.

In production environments, monitor disk usage and periodically clean /tmp/uv-cache.

Network timeouts: Some corporate networks have aggressive timeouts.

Increase uv's timeout settings:

ENV UV_HTTP_TIMEOUT=300 \
    UV_KEYRING_PROVIDER=disabled

SSL certificate problems: Corporate environments often have custom CA certificates.

Mount them or install them in the base image:

COPY custom-ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates

The bottom line: uv in Docker is production-ready, but you need to understand the specific patterns and failure modes.

This template handles the 90% case

• modify it based on your specific requirements.

Production Deployment Resources

• uv Docker integration guide
• official container setup documentation
• uv GitHub Actions guide
• CI/CD pipeline configuration
• Docker security best practices
• OWASP security guidelines for containers
• Container structure testing
• automated testing framework for container images
• [Distroless Python images](https://github.com/Google

ContainerTools/distroless)

• minimal, secure base images
• Multi-stage build optimization
• Docker's official best practices guide
• GitHub Actions cache optimization
• speeding up CI builds
• Docker BuildKit advanced features
• build performance and security enhancements
• Container monitoring with Prometheus
• production monitoring setup
• Dependency vulnerability scanning
• security auditing for Python packages
• SSL certificate management
• handling corporate certificate authorities
• Docker health checks
• container health monitoring patterns