How to Deploy Python Web Apps with Gunicorn: A Step‑by‑Step Guide

Gunicorn (Green Unicorn) is a high‑performance WSGI HTTP server widely used to deploy Python web applications; it receives client requests, forwards them to the application, and manages concurrency, running primarily on Linux (Windows via WSL).

Core concepts : Gunicorn implements the WSGI standard, supports a multi‑process model for handling concurrent requests, and works seamlessly with frameworks such as Flask and Django, offering flexible configuration options.

Installation : Install via pip install gunicorn and verify with gunicorn --version, which should display a version like gunicorn (version 23.0.0).

Deploying a Flask app :

from flask import Flask
app = Flask(__name__)
@app.route('/')
def home():
    return "Hello, Gunicorn!"
if __name__ == "__main__":
    app.run()

Run the app with gunicorn -w 4 -b 127.0.0.1:8000 app:app, where -w 4 sets four worker processes, -b 127.0.0.1:8000 binds to the local address, and app:app specifies the module and Flask instance.

Deploying a Django app :

django-admin startproject myproject
cd myproject
python manage.py runserver

Start with Gunicorn using gunicorn -w 4 -b 127.0.0.1:8000 myproject.wsgi:application, where myproject.wsgi:application points to the Django WSGI entry.

Gunicorn configuration parameters include: -w / --workers: number of worker processes (recommended CPU cores * 2 + 1). -b / --bind: address and port. --timeout: request timeout (default 30 s). --access-logfile and --error-logfile: paths for access and error logs.

Example command:

gunicorn -w 3 --timeout 120 --access-logfile access.log --error-logfile error.log -b 0.0.0.0:8000 myproject.wsgi:application

Using a configuration file ( gunicorn_config.py) allows central management:

bind = "0.0.0.0:8000"
workers = 4
timeout = 120
accesslog = "access.log"
errorlog = "error.log"
loglevel = "info"

Start with gunicorn -c gunicorn_config.py myproject.wsgi:application.

Integrating with Nginx :

server {
    listen 80;
    server_name example.com;
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    location /static/ {
        alias /path/to/staticfiles/;
    }
}

Enable the site with

sudo ln -s /etc/nginx/sites-available/myproject /etc/nginx/sites-enabled

and restart Nginx via sudo systemctl restart nginx.

Running Gunicorn as a systemd service :

[Unit]
Description=Gunicorn Daemon for Django
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/path/to/myproject
ExecStart=/path/to/venv/bin/gunicorn -c /path/to/gunicorn_config.py myproject.wsgi:application

[Install]
WantedBy=multi-user.target

Enable and start with sudo systemctl enable gunicorn and sudo systemctl start gunicorn.

Performance tuning includes setting workers = multiprocessing.cpu_count() * 2 + 1, enabling threads ( --threads 2) for I/O‑bound workloads, adjusting timeout to avoid long‑running request failures, and monitoring access and error logs.

Overall, Gunicorn combined with Nginx provides a high‑performance, easy‑to‑configure stack for deploying Python web applications; selecting appropriate worker counts, timeouts, and logging options allows optimization of resource usage and reliability.