Gunicorn — Python WSGI HTTP Server for Production

Introduction

Gunicorn (Green Unicorn) is a Python WSGI HTTP server ported from the Ruby Unicorn project. It uses a pre-fork worker model to serve Python web applications reliably behind a reverse proxy like Nginx, and is the most widely deployed Python application server in production environments.

What Gunicorn Does

• Serves any WSGI-compliant Python web application (Django, Flask, Pyramid, etc.)
• Manages a pool of worker processes that each handle requests independently
• Supports sync, async (gevent/eventlet), and gthread worker types
• Provides graceful restarts and rolling deployments with zero downtime
• Handles signal-based process management for Unix production environments

Architecture Overview

Gunicorn follows a pre-fork worker model. A master process spawns and manages multiple worker processes, each running an independent copy of the application. The master listens for signals to add or remove workers, restart gracefully, or shut down. Each worker handles one or more requests depending on the worker class: sync workers handle one request at a time, while async workers (gevent, eventlet) use green threads to multiplex many concurrent connections within a single process.

Self-Hosting & Configuration

• Install with pip install gunicorn alongside your WSGI application
• Set worker count to (2 * CPU_CORES) + 1 as a starting point
• Use --worker-class gevent for I/O-bound applications with many concurrent connections
• Configure via command-line flags, a Python config file, or environment variables
• Place behind Nginx or Caddy as a reverse proxy for static files and TLS termination

Key Features

• Drop-in server for any WSGI framework with no application code changes
• Graceful worker recycling prevents memory leaks from long-running processes
• Configurable request timeouts kill stuck workers and restart them automatically
• Built-in support for Unix sockets and systemd socket activation
• Extensible through custom worker classes and server hooks

Comparison with Similar Tools

• Uvicorn — ASGI server for async frameworks like FastAPI, not WSGI
• uWSGI — more features and protocols but significantly more complex to configure
• Waitress — pure-Python WSGI server that runs on Windows but lacks Unix signals
• mod_wsgi — Apache module approach, tightly coupled to the Apache lifecycle
• Daphne — Django Channels ASGI server, not a WSGI server

FAQ

Q: How many workers should I run? A: The general formula is (2 * CPU_CORES) + 1 for sync workers. For gevent workers handling I/O-bound loads, you can increase this since each worker uses green threads for concurrency.

Q: Can Gunicorn serve ASGI applications like FastAPI? A: No. Gunicorn is a WSGI server. For ASGI applications, use Uvicorn. You can run Uvicorn workers under Gunicorn's process manager with gunicorn -k uvicorn.workers.UvicornWorker.

Q: Do I still need Nginx in front of Gunicorn? A: It is strongly recommended. Nginx handles TLS, static files, request buffering, and slow-client protection far more efficiently than Gunicorn, which is optimized for running Python code.

Q: How do I do zero-downtime deploys? A: Send HUP to the master process. Gunicorn will spawn new workers with the updated code and gracefully shut down old workers after they finish serving current requests.

Sources

• https://github.com/benoitc/gunicorn
• https://docs.gunicorn.org/en/stable/