laurigates/python-containers

Python Container Optimization

Expert knowledge for building optimized Python container images using slim base images, virtual environments, modern package managers (uv, poetry), and multi-stage build patterns.

When to Use This Skill

| Use this skill when... | Use container-development instead when... | |------------------------|---------------------------------------------| | Building Python-specific Dockerfiles | General multi-stage build patterns | | Optimizing Python image sizes | Language-agnostic container security | | Handling pip/poetry/uv in containers | Docker Compose configuration | | Dealing with musl/glibc issues | Non-Python container optimization |

Core Expertise

Python Container Challenges:

• Large base images with unnecessary packages (~1GB)
• Critical: Alpine causes issues with Python (musl vs glibc)
• Complex dependency management (pip, poetry, pipenv, uv)
• Compiled C extensions requiring build tools
• Virtual environment handling in containers

Key Capabilities:

• Slim-based images (NOT Alpine for Python)
• Multi-stage builds with modern tools (uv recommended)
• Virtual environment optimization
• Compiled extension handling
• Non-root user configuration

Why NOT Alpine for Python

Use slim instead of Alpine for Python containers. Alpine uses musl libc which causes:

• Many wheels don't work (numpy, pandas, scipy)
• Forces compilation from source (slow builds)
• Larger final images due to build tools
• Runtime errors with native extensions

Optimized Dockerfile Pattern (uv)

The recommended pattern achieves ~80-120MB images:

# Build stage
FROM python:3.11-slim AS builder
WORKDIR /app

RUN pip install --no-cache-dir uv

# Copy dependency files
COPY pyproject.toml uv.lock ./

# Install dependencies with uv (much faster than pip)
RUN uv sync --frozen --no-dev

COPY . .

# Runtime stage
FROM python:3.11-slim
WORKDIR /app

# Install only runtime dependencies (if needed)
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    libpq5 \
    && rm -rf /var/lib/apt/lists/*

# Create non-root user
RUN addgroup --gid 1001 appgroup && \
    adduser --uid 1001 --gid 1001 --disabled-password appuser

# Copy only what's needed
COPY --from=builder --chown=appuser:appgroup /app/.venv /app/.venv
COPY --chown=appuser:appgroup app/ /app/app/
COPY --chown=appuser:appgroup pyproject.toml /app/

ENV PATH="/app/.venv/bin:$PATH" \
    PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1

USER appuser
EXPOSE 8000

HEALTHCHECK --interval=30s CMD python -c "import requests; requests.get('http://localhost:8000/health')" || exit 1

CMD ["python", "-m", "app"]

Package Manager Summary

| Manager | Speed | Command | Notes | |---------|-------|---------|-------| | uv | 10-100x faster | uv sync --frozen --no-dev | Recommended | | poetry | Standard | poetry install --only=main | Set POETRY_VIRTUALENVS_IN_PROJECT=1 | | pip | Standard | pip install --no-cache-dir --prefix=/install -r requirements.txt | Use --prefix for multi-stage |

Performance Impact

| Metric | Full (1GB) | Slim (400MB) | Multi-Stage (150MB) | Optimized (100MB) | |--------|------------|--------------|---------------------|-------------------| | Image Size | 1GB | 400MB | 150MB | 100MB | | Pull Time | 4m | 1m 30s | 35s | 20s | | Build Time (pip) | 5m | 4m | 3m | 3m | | Build Time (uv) | - | - | 45s | 30s | | Memory Usage | 600MB | 350MB | 200MB | 150MB |

Security Impact

| Image Type | Vulnerabilities | Size | Risk | |------------|-----------------|------|------| | python:3.11 (full) | 50-70 CVEs | 1GB | High | | python:3.11-slim | 12-18 CVEs | 400MB | Medium | | Multi-stage slim | 8-12 CVEs | 150MB | Low | | Distroless Python | 4-6 CVEs | 140MB | Very Low |

Agentic Optimizations

| Context | Command | Purpose | |---------|---------|---------| | Quick build | DOCKER_BUILDKIT=1 docker build -t app . | Fast build with cache | | Size check | docker images app --format "table {{.Repository}}\t{{.Size}}" | Check image size | | Layer analysis | docker history app:latest --human \| head -20 | Find large layers | | Test imports | docker run --rm app python -c "import app" | Verify imports work | | Dependency list | docker run --rm app pip list --format=freeze | See installed packages | | Security scan | docker run --rm app pip-audit | Check for vulnerabilities |

Best Practices

• Use slim NOT alpine for Python
• Use uv for fastest builds (10-100x faster than pip)
• Use multi-stage builds
• Set PYTHONUNBUFFERED=1 and PYTHONDONTWRITEBYTECODE=1
• Run as non-root user
• Use virtual environments and pin dependencies with lock files
• Use --no-cache-dir with pip

For detailed examples, advanced patterns, and best practices, see REFERENCE.md.

Related Skills

• container-development - General container patterns, multi-stage builds, security
• go-containers - Go-specific container optimizations
• nodejs-containers - Node.js-specific container optimizations