Package Python Apps in Docker with Multi-Stage Builds

Intermediate15 min

Containerize Python applications using Docker multi-stage builds for small, secure, production-ready images.

Prerequisites

-Docker installed
-A Python project with requirements.txt or pyproject.toml

Steps

Create a Dockerfile with multi-stage build

Create a multi-stage Dockerfile. The builder stage installs dependencies, and the production stage copies only the installed packages, keeping the final image small.

$ cat > Dockerfile << 'EOF' # Build stage FROM python:3.12-slim AS builder WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir --prefix=/install -r requirements.txt # Production stage FROM python:3.12-slim WORKDIR /app COPY --from=builder /install /usr/local COPY src/ ./src/ EXPOSE 8000 CMD ["python", "-m", "src.main"] EOF

Using python:3.12-slim instead of python:3.12 reduces the base image size from ~1GB to ~150MB.

Create a .dockerignore file

Exclude unnecessary files from the Docker build context. This speeds up builds and prevents sensitive files from being included in the image.

$ echo -e '.venv\n__pycache__\n*.pyc\n.git\n.pytest_cache\n.mypy_cache\n.ruff_cache' > .dockerignore

Build the Docker image

Build the Docker image from the Dockerfile in the current directory. Docker caches each layer, so subsequent builds with unchanged requirements are fast.

$ docker build -t myapp:latest .

Run the container

Start a container from the image in detached mode, mapping port 8000 on the host to port 8000 in the container.

$ docker run -d -p 8000:8000 --name myapp myapp:latest

Check the image size

Verify the final image size. A well-optimized Python image with slim base should be under 200MB for most applications.

$ docker images myapp --format 'table {{.Repository}}\t{{.Tag}}\t{{.Size}}'

If you need an even smaller image, consider python:3.12-alpine, but be aware that some Python packages with C extensions may require additional build dependencies.

Full Script

full-script.sh

#!/bin/bash
# Docker packaging workflow for Python apps
set -e

# Create Dockerfile
cat > Dockerfile << 'DOCKERFILE'
# Build stage - install dependencies
FROM python:3.12-slim AS builder
WORKDIR /build
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# Production stage - copy only what's needed
FROM python:3.12-slim
RUN useradd --create-home appuser
WORKDIR /app

COPY --from=builder /install /usr/local
COPY src/ ./src/

USER appuser
EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"
CMD ["python", "-m", "src.main"]
DOCKERFILE

# Create .dockerignore
cat > .dockerignore << 'IGNORE'
.venv
__pycache__
*.pyc
.git
.pytest_cache
.mypy_cache
.ruff_cache
*.egg-info
dist
build
IGNORE

docker build -t myapp:latest .
docker images myapp

echo "Docker image built successfully."

FAQ

Discussion

Loading comments...

#!/bin/bash # Docker packaging workflow for Python apps set -e # Create Dockerfile cat > Dockerfile << 'DOCKERFILE' # Build stage - install dependencies FROM python:3.12-slim AS builder WORKDIR /build COPY requirements.txt . RUN pip install --no-cache-dir --prefix=/install -r requirements.txt # Production stage - copy only what's needed FROM python:3.12-slim RUN useradd --create-home appuser WORKDIR /app COPY --from=builder /install /usr/local COPY src/ ./src/ USER appuser EXPOSE 8000 HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" CMD ["python", "-m", "src.main"] DOCKERFILE # Create .dockerignore cat > .dockerignore << 'IGNORE' .venv __pycache__ *.pyc .git .pytest_cache .mypy_cache .ruff_cache *.egg-info dist build IGNORE docker build -t myapp:latest . docker images myapp echo "Docker image built successfully."