Green Unicorn, commonly shortened to "Gunicorn", is a Web Server Gateway Interface (WSGI) server implementation that is commonly used to run Python web applications.
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.
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/1.8/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:
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.
There are three framework-specific posts on the Full Stack Python blog for configuring Gunicorn for development on Ubuntu:
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.
The Django and Flask documentation each contain instructions for deploying the respective frameworks with Gunicorn.
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.
Searching for a complete, step-by-step deployment walkthrough? Learn more about The Full Stack Python Guide to Deployments book.