Docker - Gunicorn

Running Gunicorn in Docker containers is the most common deployment pattern for modern Python applications. This guide covers best practices for containerizing Gunicorn applications.
Gunicorn provides an official Docker image on GitHub Container Registry:
Mount your application directory and run:
Use -d (detached mode) to run the container in the background:
For more control, build a custom image using the patterns below.
Use environment variables for configuration:
Or use GUNICORN_CMD_ARGS:
In containers, determine workers based on available CPU:
Or let Kubernetes/Docker limit CPU and calculate accordingly:
Run as a non-root user for security:
Add a health check endpoint and Docker health check:
Reduce image size with multi-stage builds:
Example docker-compose.yml:
Example Kubernetes deployment:
Gunicorn handles SIGTERM gracefully by default. Configure the timeout:
Match Docker's stop timeout:
Log to stdout/stderr for Docker log collection:
Use JSON logging for log aggregation:
If workers are killed with [CRITICAL] WORKER TIMEOUT, increase the timeout:
Or investigate slow requests in your application.
If containers are OOM-killed:
If you see connection resets, ensure: