Green Unicorn (Gunicorn)

Green Unicorn, commonly shortened to "Gunicorn", is a Web Server Gateway Interface (WSGI) server implementation that is commonly used to run Python web applications.

Why is Gunicorn important?

Gunicorn is one of many WSGI server implementations, but it's particularly important because it is a stable, commonly-used part of web app deployments that's powered some of the largest Python-powered web applications in the world, such as Instagram.

Gunicorn implements the PEP3333 WSGI server standard specification so that it can run Python web applications that implement the application interface. For example, if you write a web application with a web framework such as Django, Flask or Bottle, then your application implements the WSGI specification.

How does Gunicorn know how to run my web app?

Gunicorn knows how to run a web application based on the hook between the WSGI server and the WSGI-compliant web app.

Here is an example of a typical Django web application and how it is run by Gunicorn. We'll use the django_defaults as an example Django project. Within the django_defaults project subdirectory, there is a short wsgi.py file with the following contents:

"""
WSGI config for django_defaults project.

It exposes the WSGI callable as a module-level variable named ``application``.

For more information on this file, see
https://docs.djangoproject.com/en/3.2/howto/deployment/wsgi/
"""

import os

from django.core.wsgi import get_wsgi_application

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "django_defaults.settings")

application = get_wsgi_application()

That wsgi.py file was generated by the django-admin.py startproject command when the Django project was first created. Django exposes an application variable via that wsgi.py file so that a WSGI server can use application as a hook for running the web app. Here's how the situation looks visually:

What's a "pre-fork" worker model?

Gunicorn is based on a pre-fork worker model, compared to a worker model architecture. The pre-work worker model means that a master thread spins up workers to handle requests but otherwise does not control how those workers perform the request handling. Each worker is independent of the controller.

Gunicorn resources

• There are three framework-specific posts on the Full Stack Python blog for configuring Gunicorn for development on Ubuntu:

  1. Setting up Python 3, Django and Gunicorn on Ubuntu 16.04 LTS
  2. How to set up Python 3, Flask and Green Unicorn on Ubuntu 16.04 LTS
  3. Configuring Python 3, Bottle and Gunicorn for Development on Ubuntu 16.04 LTS

• gunicorn as your Django development server is a short post with a few good tips on using Gunicorn for local application development.

• The Full Stack Python Guide to Deployments provides detailed step-by-step instructions for deploying Gunicorn as part of an entire Python web application deployment.

• Flask on Nginx and Gunicorn combines the Nginx web server with Gunicorn in a deployment to serve up a Flask application.

• The answers to the question "what's the best practice for running Django with Gunicorn?" provide some nuance for how Gunicorn should be invokin the callable application variable provided by Django within a deployment.

• How to Install Django with Gunicorn and Nginx on FreeBSD 10.2 is a tutorial for FreeBSD, which is not often used in walkthroughs compared to the frequency that Ubuntu and CentOS tutorials appear.

• How to make a Scalable Python Web App using Flask, Gunicorn, NGINX on Ubuntu 14.04 and Deploy a Flask App on Ubuntu both provide steps for setting up a Flask web app using Gunicorn. There isn't much explanation provided with each tutorial but they can still be good concise references in case you're having issues with Ubuntu.

• Deploying a Flask Site Using Nginx, Gunicorn, Supervisor and Virtualenv on Ubuntu is a similar tutorial to the previous two links. It provides some good screenshots along the way with what to expect while you are configuring the deployment server.

• The Django and Flask documentation each contain instructions for deploying the respective frameworks with Gunicorn.

• Dockerizing Django with Postgres, Gunicorn, and Traefik is a more advanced tutorial with a complete project deployment that uses Gunicorn within Docker.

• Set up Django, Nginx and Gunicorn in a Virtualenv controled by Supervisor is a GitHub Gist with some great explanations for why we're setting up virtualenv and what to watch out for while you're doing the deployment.

• The Gunicorn design document is worth reading because it describes the server model and gives some context on how to choose the number of workers for your execution environment.

• Configuring Gunicorn for containers explains how to avoid excessive slowness in your Docker containers that run Gunicorn workers, as well as some tips on proper logging.

What else do you want to learn about deployments?