Installing Gunicorn: A Practical Guide for Django and Flask

Gunicorn (Green Unicorn) is a Python WSGI HTTP server used to run web apps like Django and Flask in production. Installing it takes one command; the part worth getting right is how you launch your app and a platform limitation that stops many people before they start.

Install Gunicorn

Gunicorn is a standard PyPI package. Inside your project's virtual environment:

pip install gunicorn

Verify it's installed and check the version:

gunicorn --version

Add it to your dependency file so deployments are reproducible — for example a line in requirements.txt:

gunicorn==23.0.0

Run a Django app

Gunicorn serves your app through its WSGI entry point. For a Django project, that's the application callable in your project's wsgi.py. From the directory containing manage.py:

gunicorn myproject.wsgi:application

Replace myproject with the folder that holds your settings.py and wsgi.py. The syntax is module:callable — the part before the colon is the import path, the part after is the WSGI callable inside it.

Run a Flask app

For Flask, point Gunicorn at the module and the app object. If your app is defined as app = Flask(__name__) in app.py:

gunicorn app:app

The first app is the file (app.py), the second is the Flask instance inside it.

Common options: bind and workers

By default Gunicorn binds to 127.0.0.1:8000, which only accepts local connections. To listen on all interfaces (for example behind a reverse proxy like Nginx), set the bind address, and set the number of worker processes:

gunicorn myproject.wsgi:application --bind 0.0.0.0:8000 --workers 3

A common starting point for worker count is (2 × number_of_CPU_cores) + 1. Each sync worker handles one request at a time, so more workers means more concurrent requests — up to what your CPU and memory allow. Tune from there based on your workload.

The Windows gotcha

Gunicorn does not run natively on Windows. It depends on Unix-only facilities (such as the fcntl module and the fork-based worker model), so pip install gunicorn may succeed but gunicorn will fail to run on native Windows. If you're on Windows, run it inside WSL (Windows Subsystem for Linux), in a Linux container, or on a Linux server — or use a Windows-compatible WSGI server like Waitress for local development instead.

A note on async apps

Gunicorn is a WSGI server, which covers standard Django and Flask. If you're running an ASGI/async app (FastAPI, or Django in ASGI mode), you'll want an ASGI-capable setup — for example Gunicorn managing Uvicorn workers, or running Uvicorn directly. Plain sync Gunicorn won't serve an ASGI app as-is.

Once installed, Gunicorn is typically run behind a reverse proxy and managed by a process supervisor in production — a setup that's easy to get subtly wrong. I build and deploy Django backends as part of my work; if you need a hand with backend or infrastructure, check out Netalith's services or reach out to me on LinkedIn.