Skip to main content
Gunicorn is a Python WSGI HTTP server that runs Flask, Django and other WSGI applications in production. This guide shows how to start your application with Gunicorn, tune it for the RAM of your plan and run it on Square Cloud.

​
Install Gunicorn

Install Gunicorn on your machine:
Add gunicorn to your requirements.txt too, so Square Cloud installs it with your other dependencies:
requirements.txt

​
Basic usage

To run an application with Gunicorn, you need a WSGI application, such as one built with Flask or Django, and you need to know the module name and the variable name that holds the WSGI application object. For example, if you have a Flask application in a file named app.py and the Flask instance is named app, you can run it with Gunicorn using the following command:
In this command:
  • python -m gunicorn runs Gunicorn as a Python module.
  • --bind 0.0.0.0:80 tells Gunicorn to listen on all network interfaces on port 80.
  • app:app specifies the module name (app) and the variable name (app) that contains the WSGI application object.
For Django, point Gunicorn to the wsgi.py module Django creates inside your project package (replace myproject with your project’s name):

​
Additional options

Gunicorn provides several options to customize its behavior. These are the most common ones; the official Gunicorn settings reference lists them all.

​
Workers

  • --workers <number>
This option sets the number of worker processes for handling requests. Each worker is a separate process with its own copy of your application in memory, so on Square Cloud the limit is usually RAM, not CPU. Start with 2 workers and add more only after raising MEMORY. If your application stops with LACK_OF_RAM, lower the number of workers.
Don’t size workers with multiprocessing.cpu_count() or the (2 x $num_cores) + 1 formula: inside a container, the core count can be the host machine’s, which starts dozens of workers and exhausts your RAM.

​
Name

  • --name <name>
  • -n <name>
This option sets the process name for Gunicorn.

​
Worker class

  • --worker-class <class>
  • -k <class>
This option sets the type of worker to use. The default is sync, but you can also use gevent, eventlet, tornado or other worker type.

​
Config file

You can also set Gunicorn options in a Python configuration file. Gunicorn automatically loads a file named gunicorn.conf.py from the directory where it runs, which is your project root on Square Cloud. For any other file name, pass it with -c <file>.
gunicorn.conf.py
With this file in your project, the start command no longer needs the --bind option.

​
Run it on Square Cloud

Create a squarecloud.app file at the root of your project and put the Gunicorn command in its START field, so Square Cloud starts your application with Gunicorn instead of the default python app.py:
Gunicorn must bind to 0.0.0.0:80: Square Cloud delivers your subdomain’s traffic to port 80 of your application. Square Cloud also sets the PORT environment variable to 80, and Gunicorn reads it: without a --bind option, it listens on 0.0.0.0:$PORT when PORT is set.
For Django, use myproject.wsgi:application in START and your project’s manage.py as MAIN. The Flask and Django tutorials cover the full deploy.

​
Next steps

Flask

Deploy a Flask application behind Gunicorn.

Django

Deploy a Django project behind Gunicorn.

App won't start

Fix EADDRINUSE, LACK_OF_RAM and other startup failures.

​
Did you like this article?

  • We created this content with great care to offer the best help possible. If this article helped you in any way, support our work! Developers have already rated Square Cloud 4.9/5 across 402 reviews on Google and Trustpilot: leave yours too! It helps us understand what matters most to you.

Google Reviews

Leave your review in Google Reviews.

Trustpilot

Leave your review in Trustpilot.