Gunicorn

Definition

Gunicorn, short for Green Unicorn, is a WSGI (Web Server Gateway Interface) HTTP server for Python web applications, designed to run under Unix-like operating systems. It uses a pre-fork worker model, meaning a central master process forks multiple worker processes that each handle requests independently, which makes it a common choice for serving synchronous frameworks such as Flask and Django in production.

Overview

Before Gunicorn, Python web developers running frameworks like Flask or Django in production often relied on Apache with mod_wsgi or hand-rolled server setups that were awkward to configure and did not scale cleanly across CPU cores. Gunicorn was created to give Python applications a straightforward, Unix-native process model for handling concurrent HTTP traffic without requiring a full application server stack. Mechanically, Gunicorn follows a pre-fork master-worker architecture borrowed from servers like Unicorn in the Ruby ecosystem, from which it takes its name. A master process binds to a port and forks a configurable number of worker processes, each of which independently accepts connections and processes requests using the WSGI interface. Because workers are separate OS processes, a crash in one worker does not take down the others, and the master process can restart failed workers automatically. Gunicorn supports multiple worker classes, including synchronous workers that handle one request at a time per process, and async worker classes like `gevent` or `eventlet` that allow a single worker to juggle many concurrent I/O-bound requests. Within the Python serving ecosystem, Gunicorn sits alongside servers like uWSGI as a mature, battle-tested WSGI implementation, and is often contrasted with Uvicorn, which speaks the newer ASGI protocol for async-native frameworks. Because Gunicorn's process-management features are strong but its native worker types are synchronous, it is frequently paired with Uvicorn's worker class to combine Gunicorn's supervision with async request handling. In practice, Gunicorn is deployed behind a reverse proxy such as Nginx, which handles static files, TLS termination, and buffering slow clients, while Gunicorn focuses purely on running the Python application logic. Operators tune the worker count based on CPU cores and workload type, and use Gunicorn's configuration file or command-line flags to set timeouts, logging, and graceful reload behavior for zero-downtime deployments. Gunicorn's main limitation is that its default sync workers block on I/O, so a slow database query or external API call ties up an entire worker process until it completes, which can exhaust available workers under high concurrency. It also does not natively support ASGI features like WebSockets without additional async worker classes, and it assumes a Unix-like environment, since it does not run on Windows. Operators typically address the blocking-worker limitation either by increasing the worker count to absorb more concurrent slow requests, at the cost of higher memory usage, or by switching to an async worker class so a smaller number of workers can each juggle many in-flight connections. Because Gunicorn predates the ASGI standard, most of its documentation and community tooling still centers on synchronous WSGI patterns, so teams building new async-first services increasingly choose to run Uvicorn directly, or under Gunicorn's supervision, rather than relying on Gunicorn's own async worker classes as the primary concurrency model.

Key Features

• Pre-fork master-worker process model for handling concurrent requests
• Supports the WSGI interface used by Flask, Django, and similar frameworks
• Offers synchronous and async worker classes including gevent and eventlet
• Provides automatic worker recycling and crash recovery
• Supports graceful reloads for zero-downtime deployments
• Configurable via command-line flags or a Python configuration file
• Integrates with process managers like systemd and supervisord
• Works well behind reverse proxies such as Nginx

Use Cases

Alternatives

Frequently Asked Questions

Related in Web