gunicorn

What Is Gunicorn?

Gunicorn, short for "Green Unicorn," is a Python WSGI HTTP server used to run web applications written with frameworks like Django and Flask. It sits between your application code and the outside world, translating incoming HTTP requests into the standardized WSGI calls that Python web frameworks understand, then sending the responses back out. If you have ever seen a Python web app described as running "behind Nginx with Gunicorn," that phrase captures exactly the role Gunicorn plays: it is the application server that actually executes your Python code on each request.

Gunicorn is widely regarded as one of the most popular production WSGI servers in the Python ecosystem. It is open source, broadly adopted, and frequently the default recommendation in deployment tutorials for Django and Flask, precisely because it is simple to configure, stable under load, and free of heavy dependencies. It is not a framework, not a full web server in the traditional sense, and certainly not a browser extension; it is a focused piece of infrastructure whose job is to run your Python application reliably.

A WSGI server exists because Python web frameworks do not, by themselves, speak HTTP efficiently to the public internet. WSGI (the Web Server Gateway Interface) is a specification that defines a clean contract between web servers and Python applications. Gunicorn implements the server side of that contract. It loads your application once, then manages a pool of worker processes that each handle requests, so your Flask or Django code can stay focused on business logic rather than on the mechanics of sockets, concurrency, and process management.

It helps to understand where Gunicorn sits in a typical stack. In most production deployments, a front-end web server or reverse proxy such as Nginx faces the internet, terminates TLS, serves static files, and forwards dynamic requests to Gunicorn over a local socket. Gunicorn then runs the Python application and returns the response. This separation of concerns, with a hardened reverse proxy in front and an application server behind it, is the standard pattern for deploying Python web apps, and it is the architecture Gunicorn was designed to fit into.

How Gunicorn Works

Gunicorn uses a pre-fork worker model, an approach borrowed from the venerable Unicorn server in the Ruby world (hence the name). When Gunicorn starts, a single master process loads the application and then forks a configurable number of worker processes. The master never handles requests itself; instead, it supervises the workers, restarts any that crash or time out, and coordinates graceful reloads. Each worker independently accepts connections and runs your Python code, which gives the server resilience: if one worker hangs or dies, the others keep serving traffic while the master replaces the failed one.

The choice of worker type is central to how Gunicorn behaves. The default synchronous worker handles one request at a time per process, which is simple and robust for typical CPU-bound or fast database-backed views. For workloads with many slow or long-lived connections, Gunicorn supports asynchronous workers based on libraries such as gevent and eventlet, as well as threaded workers and integration with ASGI-style async stacks through compatible worker classes. Operators tune the number of workers and threads to match the number of CPU cores and the nature of the workload, balancing throughput against memory use.

Configuration is flexible. Gunicorn can be driven entirely from command-line flags, from a Python configuration file, or from environment variables, which makes it easy to slot into containerized and platform-as-a-service deployments. A typical invocation looks like gunicorn myproject.wsgi:application --workers 4 --bind 127.0.0.1:8000, telling Gunicorn which application callable to load, how many workers to run, and which socket to listen on.

In production, Gunicorn almost always runs behind a reverse proxy rather than facing the internet directly. Nginx (or another front-end server) handles TLS termination, serves static assets, buffers slow clients, and forwards application requests to Gunicorn over a Unix socket or local TCP port. This arrangement protects Gunicorn from slow-client attacks, offloads static file serving, and lets the proxy add caching and compression. The Gunicorn project itself recommends running behind a buffering proxy for exactly these reasons. A process manager such as systemd, supervisord, or a container orchestrator keeps the Gunicorn master alive, restarts it on failure, and manages logging.

Because Gunicorn loads the application into long-lived worker processes, it keeps the framework, imported modules, and database connection pools warm between requests, which is far more efficient than spawning a fresh interpreter per request. Graceful reloads let operators deploy new code by signaling the master to cycle workers without dropping in-flight requests, an important property for zero-downtime deployments.

How to Tell if a Website Uses Gunicorn

Gunicorn can sometimes be identified from the outside, but with an important caveat: in well-architected deployments it sits behind a reverse proxy that strips or overrides its identifying headers. StackOptic analyzes a URL from the server side and inspects the same response signals you can check by hand, while recognizing that those signals are frequently masked.

The Server response header. Gunicorn's most direct fingerprint is the HTTP Server header. When Gunicorn answers a request directly, it sends Server: gunicorn (sometimes with a version, such as Server: gunicorn/21.2.0). You can check this with curl -I https://example.com and look at the Server line. The catch is that a fronting proxy like Nginx usually replaces this header with its own value (for example Server: nginx), so the absence of a Gunicorn header does not rule it out.

Combination with a Python framework. Because Gunicorn runs Python applications, detecting Django or Flask alongside a generic or proxy Server header is suggestive. Django's csrftoken and sessionid cookies, or Flask's signed session cookie format, hint at a Python back end that is very likely served by a WSGI server such as Gunicorn even when the server name is hidden. The techniques in our guide on how to find out what programming language a website uses help establish the Python layer.

Error pages and timeouts. In some misconfigured or development setups, Gunicorn's own error responses or worker-timeout behavior can surface, occasionally revealing the server. This is unreliable on production sites and should never be the sole basis for a conclusion.

Method	What to do	What it may reveal
curl -I	Run curl -I https://example.com	A Server: gunicorn header when not proxied
View Source / DevTools	Inspect headers and cookies in the Network tab	Django/Flask cookies suggesting a WSGI back end
Wappalyzer	Run the extension on the live page	May list Gunicorn, Django, or Flask if signals are present
BuiltWith	Look up the domain	Possible Gunicorn or Python framework detection
HTTP header reading	Examine all response headers	Server name, proxy hints, framework cookies

A quick terminal check is curl -sI https://example.com | grep -i server. If it returns gunicorn, the application server is exposed; if it returns nginx or nothing useful, Gunicorn may still be present but hidden behind a proxy. For a deeper walkthrough of header analysis, see our guides on how to read a website's HTTP headers and how to find out what server software a website runs.

It is worth being candid about the limits here. Server-side application servers like Gunicorn are, by design, often invisible to outside observers because the recommended production architecture places a reverse proxy in front of them. That proxy commonly overwrites the Server header, terminates TLS, and presents a uniform public face, so the most direct Gunicorn fingerprint simply never reaches the client. As a result, confident detection usually rests on indirect evidence: identifying a Python framework through its cookies and behavior, then inferring that a WSGI server such as Gunicorn is doing the work behind the proxy. A single signal is rarely conclusive, which is exactly why automated analysis weighs several clues together rather than trusting one header. When the Server header is present and says gunicorn, the verdict is easy; when it is masked, the honest answer is a probability rather than a certainty.

Key Features

• Pre-fork worker model. A supervising master process forks and manages multiple workers for resilience and parallelism.
• Pluggable worker types. Synchronous, threaded, and asynchronous (gevent, eventlet) workers to match different workloads.
• Simple configuration. Driven by command-line flags, a Python config file, or environment variables, ideal for containers and PaaS.
• Graceful reloads. Cycle workers to deploy new code without dropping in-flight requests.
• Framework agnostic within WSGI. Runs any WSGI-compliant app, including Django, Flask, Pyramid, and Bottle.
• Low overhead. Lightweight, dependency-light, and battle-tested in production Python deployments.
• Process supervision. Automatically restarts crashed or timed-out workers to keep the service healthy.

Pros and Cons

Pros

• Simple, stable, and easy to configure, which is why it is the default in countless Python deployment guides.
• Robust pre-fork model isolates failures to individual workers.
• Flexible worker types let the same server handle CPU-bound and I/O-bound workloads.
• Integrates cleanly with reverse proxies, process managers, and container platforms.

Cons

• Not intended to face the internet alone; it needs a reverse proxy in front for TLS, static files, and slow-client protection.
• Synchronous workers can be inefficient for highly concurrent, long-lived connections without async worker classes.
• Primarily a Unix-oriented server, with limited native support on some platforms.
• Tuning worker and thread counts for a given workload requires some operational knowledge.

Gunicorn vs Alternatives

Gunicorn is one of several application servers used to run Python web apps. The table below shows where it fits relative to common alternatives.

Server	Model	Best for	Notes
Gunicorn	Pre-fork WSGI	Django/Flask in production	Simple, stable, proxy-fronted default
uWSGI	Highly configurable WSGI	Complex, tunable deployments	Powerful but with a steeper learning curve
uvicorn	ASGI server	Async frameworks (FastAPI, Starlette)	Built for async/await and websockets
mod_wsgi	Apache module	Apache-centric stacks	Embeds Python in the Apache process
Waitress	Pure-Python WSGI	Cross-platform, no C deps	Works well on Windows and simple setups

Gunicorn is frequently paired with uvicorn workers to serve async ASGI applications while keeping Gunicorn's process management. To explore the framework that most commonly sits on top of Gunicorn, see Django, and to understand the reverse proxy usually placed in front of it, our hosting guides cover that layer in depth.

Use Cases

Gunicorn's primary use case is serving production Python web applications. Teams deploying Django projects reach for it as the default application server, pairing it with Nginx and a process manager to run reliable, multi-worker services. Flask APIs and microservices follow the same pattern, with Gunicorn providing the concurrency and supervision that the development server cannot offer safely.

It is equally at home inside containers. A typical Docker image for a Python web service runs Gunicorn as its entrypoint, with the number of workers set from an environment variable so the same image scales across environments. Platform-as-a-service providers and orchestration systems frequently expect a Gunicorn command as the process that boots the app. Data and machine-learning teams also use Gunicorn to expose model-inference endpoints, wrapping a prediction function in a small Flask or FastAPI app and serving it behind a proxy.

For competitive and infrastructure research, identifying Gunicorn, or inferring it from a detected Python framework, signals a Python-based back end and an engineering team comfortable with self-managed or container-based deployments. That is useful context for vendors selling developer tooling, hosting, observability, or Python-specific services. Because the server itself is often masked, analysts typically treat a confirmed Python framework as the practical proxy for "almost certainly running a WSGI server like Gunicorn," and combine that with hosting signals to build a fuller picture of the stack. Understanding the technology profile of a prospect this way is a core part of what our guide on using tech-stack data to qualify leads describes.

Frequently Asked Questions

Is Gunicorn a web server?

Gunicorn is an application server, more precisely a WSGI HTTP server, rather than a general-purpose web server like Nginx or Apache. It speaks HTTP and runs your Python application, but in production it is designed to sit behind a reverse proxy that handles TLS, static files, and slow clients. So while it does serve HTTP, it fills a narrower role than a full front-end web server and is almost always deployed alongside one.

Can you detect Gunicorn from the outside?

Sometimes. If Gunicorn answers requests directly, its Server: gunicorn header is visible to a simple curl -I check. In most production setups, however, a reverse proxy overwrites that header, so Gunicorn is hidden. In those cases detection relies on inferring a Python framework (through Django or Flask cookies, for example) and concluding that a WSGI server such as Gunicorn is very likely running behind the proxy. A masked server makes certainty difficult.

What is the difference between Gunicorn and Nginx?

Nginx is a front-end web server and reverse proxy that faces the internet, terminates TLS, serves static files, and forwards dynamic requests. Gunicorn is the application server behind Nginx that actually executes the Python code. They are complementary rather than competing: a common production stack runs Nginx in front of Gunicorn, each doing the job it is best suited for.

Why does Gunicorn use multiple workers?

A single process can only do so much, and Python's threading model limits CPU parallelism within one process. By forking multiple worker processes, Gunicorn handles many requests in parallel and isolates failures, so a crash or timeout in one worker does not take down the whole service. The master process supervises the pool, restarting workers as needed, which is what gives Gunicorn its production resilience.

Does Gunicorn work with async frameworks like FastAPI?

Yes, indirectly. Gunicorn itself implements WSGI, but it can run ASGI applications such as FastAPI by using uvicorn worker classes. In that arrangement Gunicorn provides process management and worker supervision while uvicorn handles the async event loop and websockets. Many teams deploy FastAPI as "Gunicorn managing uvicorn workers" to get the best of both.

Want to identify the back-end stack, including likely application servers, behind any site? Run a URL through StackOptic at https://stackoptic.com.