Docker Best Practices for Python in Production

This article is based on Episode 222 of the Podcast.__init__ podcast, hosted by Tobias Macey, featuring guest Itamar Turner-Trauring. The discussion covers practical best practices for running Python applications in Docker in production environments.

Why Docker and Python Require Special Attention

Docker has become a standard tool for packaging and deploying software, but it introduces its own set of complexities that teams must understand before relying on it in production. For Python specifically, the interaction between Docker’s layer-based build system, Python’s packaging ecosystem, and runtime behavior creates pitfalls that are not always obvious. Getting these right has a direct impact on build speed, image size, security posture, and operational reliability.

Common Docker Issues for Python Developers

Several recurring problems affect Python teams adopting Docker:

• Slow image builds: Python dependency installation via pip can be time-consuming. Without careful Dockerfile structuring, every code change triggers a full reinstall of all dependencies, wasting significant developer time.
• Large image sizes: Base images that include build toolchains, compilers, and header files balloon in size if they are not cleaned up or replaced with a slimmer runtime image.
• Improper layer ordering: Placing frequently changing files (like application source code) before infrequently changing files (like requirements.txt) invalidates the Docker build cache unnecessarily.
• Python-specific runtime quirks: Python’s default stdout buffering behavior, signal handling, and process management inside containers can cause unexpected issues with log delivery and graceful shutdown.

Optimizing the Docker Build Cache for Python

One of the most impactful changes you can make to a Python Dockerfile is to copy and install dependencies before copying your application code. This ensures that Docker reuses the cached dependency layer on most builds.

# Good: install dependencies first, then copy application code
FROM python:3.11-slim

WORKDIR /app

# Copy only the requirements file first
COPY requirements.txt .

# Install dependencies (this layer is cached unless requirements.txt changes)
RUN pip install --no-cache-dir -r requirements.txt

# Now copy the rest of the application
COPY . .

CMD ["python", "-m", "myapp"]Code language: PHP (php)

This pattern keeps the expensive pip install step cached during the inner development loop, so only actual dependency changes trigger a reinstall.

Using Multi-Stage Builds to Reduce Image Size

Many Python packages require C extensions that need build tools (gcc, make, header files) to compile. Those tools are unnecessary at runtime. Multi-stage builds let you compile in one stage and copy only the resulting artifacts into a smaller runtime image.

# Stage 1: build
FROM python:3.11 AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --prefix=/install --no-cache-dir -r requirements.txt

# Stage 2: runtime
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /install /usr/local
COPY . .
CMD ["python", "-m", "myapp"]Code language: PHP (php)

This approach can dramatically reduce final image size by excluding compilers, header files, and other build-time-only tools from the image that ships to production.

Security Considerations

Security is an area where many Docker deployments fall short, especially when teams rely on public images or copy-pasted Dockerfiles without review:

• Running as root: By default, processes in a Docker container run as root. This is a significant risk if a vulnerability is exploited. Always add a non-root user in your Dockerfile and use it at runtime.
• Using unpinned base images: Referencing python:latest or python:3.11 without a digest means the base image can change silently between builds, introducing unexpected changes or vulnerabilities.
• Secrets baked into images: Environment variables or files containing API keys and passwords should never be added during the RUN or COPY steps, as they persist in image layers even if deleted later.
• Outdated base images: Public images on Docker Hub are not always kept up to date with security patches. Regularly rebuild your images against updated base images.

# Add a non-root user
RUN adduser --disabled-password --gecos '' appuser
USER appuserCode language: PHP (php)

Python-Specific Runtime Gotchas Inside Docker

Beyond the build process, Python’s runtime behavior inside containers deserves attention:

• Stdout buffering: Python buffers stdout by default, which means log output may not appear in docker logs in real time. Use the -u flag or set the PYTHONUNBUFFERED=1 environment variable to disable buffering.
• Signal handling: Docker sends a SIGTERM to the main process when stopping a container. Python applications need to handle this signal explicitly to perform graceful shutdowns. Using an init process (such as tini) can help by correctly forwarding signals to child processes.
• PID 1 problem: When your Python process runs as PID 1 inside a container, it does not inherit the default signal handlers that a normal init system would provide. Tools like tini or the --init flag in Docker address this.

# Set PYTHONUNBUFFERED to ensure logs are flushed immediately
ENV PYTHONUNBUFFERED=1

# Use tini as an init process (requires tini to be installed in the image)
ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["python", "-m", "myapp"]Code language: PHP (php)

Alternatives to Dockerfile and When to Consider Them

The Dockerfile format has well-known limitations: it is sequential, has limited conditionals, and cache invalidation can be unpredictable. Several tools have emerged to address these shortcomings:

• BuildKit: Docker’s next-generation build backend (now default in recent Docker versions) offers improved caching, parallel build stages, secret mounting, and SSH forwarding without leaking credentials into layers.
• Buildah and Podman: OCI-compliant tools for building and running containers without requiring a Docker daemon, useful in environments where running Docker is not practical.
• Nix-based builders and Bazel: Reproducible build tools that can produce container images as artifacts, offering stronger guarantees about build repeatability.

When Docker Is Not the Right Choice

Docker is not universally the best deployment mechanism for Python applications. Consider alternatives when:

• Your team lacks the operational expertise to manage container infrastructure securely and reliably.
• Your application is a simple script or utility where the overhead of containerization outweighs the benefits.
• Startup latency is critical and the container cold-start time is unacceptable.

Alternatives worth evaluating for Python deployments include:

• Virtual environments with system packages: For simpler setups, deploying a Python virtual environment directly to a server remains predictable and easy to reason about.
• Shiv or PEX: Tools that package a Python application and its dependencies into a single executable zip file, eliminating the need for a container runtime.
• Conda packages or system packages: Distributing Python applications as system-level packages can simplify deployment in environments that already manage packages through an OS package manager.
• Serverless platforms: For event-driven workloads, deploying individual Python functions to a managed serverless platform may be simpler and cheaper than maintaining container infrastructure.

Key Takeaways

• Order Dockerfile instructions to maximize cache reuse: copy and install requirements.txt before copying application code.
• Use multi-stage builds to keep production images lean by excluding build toolchains.
• Never run production containers as root; always specify a non-root user.
• Set PYTHONUNBUFFERED=1 to ensure logs are not silently buffered inside the container.
• Use an init process like tini to handle signals correctly when Python runs as PID 1.
• Pin base image versions and rebuild regularly to pick up security patches.
• Evaluate whether Docker is genuinely the right fit for your deployment scenario before committing to it.

For a deeper discussion of these topics, listen to Podcast.__init__ Episode 222, where Itamar Turner-Trauring covers these issues in depth with host Tobias Macey.