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.

## 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

**⚠️ CRITICAL**: Do NOT use Alpine for Python containers!

```dockerfile
# ❌ BAD: Alpine + Python = Problems
FROM python:3.11-alpine
# Will have issues with numpy, pandas, psycopg2, pillow, etc.
```

**Problems with Alpine + Python**:
- musl libc vs glibc incompatibility
- 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

**✅ Use `slim` instead**: Python slim images are based on Debian with minimal packages.

## The Optimization Journey: 1GB → 80-120MB

### Step 1: The Problem - Full Python Base (1GB)

```dockerfile
# ❌ BAD: Full Debian with all dev packages
FROM python:3.11
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]
```

**Issues**:
- Full Debian base (~120MB)
- Build tools and compilers (~400MB)
- Unnecessary system packages
- All pip cache included

**Image size: ~1GB**

### Step 2: Slim Base (400MB)

```dockerfile
# ✅ BETTER: Slim removes unnecessary packages
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "app.py"]
```

**Im