Custom Application

New in version 19.0.

Sometimes, you want to integrate Gunicorn with your WSGI application. In this case, you can inherit from gunicorn.app.base.BaseApplication.

Here is a small example where we create a very small WSGI app and load it with a custom Application:

  1. import multiprocessing
  3. import gunicorn.app.base
  6. def number_of_workers():
  7.     return (multiprocessing.cpu_count() * 2) + 1
  10. def handler_app(environ, start_response):
  11.     response_body = b'Works fine'
  12.     status = '200 OK'
  14.     response_headers = [
  15.         ('Content-Type', 'text/plain'),
  16.     ]
  18.     start_response(status, response_headers)
  20.     return [response_body]
  23. class StandaloneApplication(gunicorn.app.base.BaseApplication):
  25.     def __init__(self, app, options=None):
  26.         self.options = options or {}
  27.         self.application = app
  28.         super().__init__()
  30.     def load_config(self):
  31.         config = {key: value for key, value in self.options.items()
  32.                   if key in self.cfg.settings and value is not None}
  33.         for key, value in config.items():
  34.             self.cfg.set(key.lower(), value)
  36.     def load(self):
  37.         return self.application
  40. if __name__ == '__main__':
  41.     options = {
  42.         'bind': '%s:%s' % ('127.0.0.1', '8080'),
  43.         'workers': number_of_workers(),
  44.     }
  45.     StandaloneApplication(handler_app, options).run()

Direct Usage of Existing WSGI Apps

If necessary, you can run Gunicorn straight from Python, allowing you to specify a WSGI-compatible application at runtime. This can be handy for rolling deploys or in the case of using PEX files to deploy your application, as the app and Gunicorn can be bundled in the same PEX file. Gunicorn has this functionality built-in as a first class citizen known as gunicorn.app.wsgiapp. This can be used to run WSGI-compatible app instances such as those produced by Flask or Django. Assuming your WSGI API package is exampleapi, and your application instance is app, this is all you need to get going:

  1. gunicorn.app.wsgiapp exampleapi:app

This command will work with any Gunicorn CLI parameters or a config file - just pass them along as if you’re directly giving them to Gunicorn:

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

Note for those using PEX: use -c gunicorn as your entry at build time, and your compiled app should work with the entry point passed to it at run time.

  1. # Generic pex build command via bash from root of exampleapi project
  2. $ pex . -v -c gunicorn -o compiledapp.pex
  3. # Running it
  4. ./compiledapp.pex exampleapi:app -c gunicorn_config.py