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