python-containers

created	"2026-01-15T00:00:00.000Z"
modified	"2026-05-09T00:00:00.000Z"
reviewed	"2026-01-15T00:00:00.000Z"
name	python-containers
description	Python container optimization — slim images (not Alpine), virtualenv, multi-stage, pip/poetry/uv, musl gotchas (1GB to ~120MB). Use when working with Python containers or optimizing image sizes.
user-invocable	false
allowed-tools	Bash, Read, Grep, Glob, Edit, Write, TodoWrite, WebSearch, WebFetch

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