Custom Application

Added in 19.0

Use Gunicorn as part of your own WSGI application by subclassing gunicorn.app.base.BaseApplication.

Example: create a tiny WSGI app and load it with a custom application:

#!/usr/bin/env python
#
# An example of a standalone application using the internal API of Gunicorn.
#
#   $ python standalone_app.py
#
# This file is part of gunicorn released under the MIT license.
# See the NOTICE for more information.

import multiprocessing

import gunicorn.app.base


def number_of_workers():
    return (multiprocessing.cpu_count() * 2) + 1


def handler_app(environ, start_response):
    response_body = b'Works fine'
    status = '200 OK'

    response_headers = [
        ('Content-Type', 'text/plain'),
    ]

    start_response(status, response_headers)

    return [response_body]


class StandaloneApplication(gunicorn.app.base.BaseApplication):

    def __init__(self, app, options=None):
        self.options = options or {}
        self.application = app
        super().__init__()

    def load_config(self):
        config = {key: value for key, value in self.options.items()
                  if key in self.cfg.settings and value is not None}
        for key, value in config.items():
            self.cfg.set(key.lower(), value)

    def load(self):
        return self.application


if __name__ == '__main__':
    options = {
        'bind': '%s:%s' % ('127.0.0.1', '8080'),
        'workers': number_of_workers(),
    }
    StandaloneApplication(handler_app, options).run()

Using server hooks

Provide hooks through configuration, just like a standard Gunicorn deployment. For example, a pre_fork hook:

def pre_fork(server, worker):
    print(f"pre-fork server {server} worker {worker}", file=sys.stderr)

if __name__ == "__main__":
    options = {
        "bind": "127.0.0.1:8080",
        "workers": number_of_workers(),
        "pre_fork": pre_fork,
    }

Direct usage of existing WSGI apps

Run Gunicorn from Python to serve a WSGI application instance at runtime—useful for rolling deploys or packaging with PEX. Gunicorn exposes gunicorn.app.wsgiapp, which accepts any WSGI app (for example a Flask or Django instance). Assuming your package is exampleapi and the application is app:

python -m gunicorn.app.wsgiapp exampleapi:app

All CLI flags and configuration files still apply:

# Custom parameters
python -m gunicorn.app.wsgiapp exampleapi:app --bind=0.0.0.0:8081 --workers=4
# Using a config file
python -m gunicorn.app.wsgiapp exampleapi:app -c config.py

For PEX builds use -c gunicorn at build time so the packaged app accepts the entry point at runtime:

pex . -v -c gunicorn -o compiledapp.pex
./compiledapp.pex exampleapi:app -c gunicorn_config.py