Python Container Optimization Skill

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

Agent Skills: Python Container Optimization

Install this agent skill to your local

Skill Files