Skip to content

# 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:

    #
    # This file is part of gunicorn released under the MIT license.
    # See the NOTICE for more information.

    #!/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