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:

# Both stages MUST share this interpreter version — see below.
ARG PYTHON_VERSION=3.11

# Build stage
FROM python:${PYTHON_VERSION}-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:${PYTHON_VERSION}-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"]