How to Configure Gunicorn in Production on Square Cloud

If you have been developing web applications with Python using frameworks like Django or Flask, you know that running the built-in development server (flask run or python app.py) is not an option for the real world. They cannot handle the load of multiple simultaneous requests.

To deploy your application with performance and stability, you need a battle-tested WSGI server: Gunicorn (Green Unicorn).

Below, see how to orchestrate Gunicorn perfectly within the Square Cloud environment, which already handles the 0.0.0.0 host and the default port 80 for you.

1. Declaring Dependencies

Since Square handles the installation for you automatically, your only job is to ensure that Gunicorn is listed as a project dependency.

If you use requirements.txt, add the line:

gunicorn

If your project uses the official pyproject.toml standard (PEP 621), add it to the project dependencies section:

[project]
dependencies = [
    "gunicorn>=23.0.0",
]

When uploading the project, Square will read these files and leave the Gunicorn module ready for use.

2. Understanding the Command

To ensure that Gunicorn is executed exactly by the isolated Python interpreter of your container on Square, the best practice is to call it as a module using the -m flag:

python -m gunicorn [options] module_name:application_attribute

• module_name: The name of the .py file where your application is located (e.g., main or wsgi).
• application_attribute: The variable that receives the instance of your framework (usually called app or application).

Practical Example with Flask

If you have a file in the root directory named wsgi.py:

from my_project import app

if __name__ == "__main__":
    app.run()

The command for Gunicorn to manage this app will be python -m gunicorn wsgi:app.

3. Configuring Host, Port, and Workers for Square

For the Square container to receive internet traffic and distribute it to your app, you must bind the server to the 0.0.0.0 host and port 80.

The ideal startup command looks like this:

python -m gunicorn --bind 0.0.0.0:80 --workers 3 wsgi:app

What does each parameter do here?

• --bind 0.0.0.0:80 (or -b): Binds Gunicorn to all network interfaces of the container on the default HTTP port (80), allowing Square to deliver external requests directly to your app.
• --workers 3 (or -w): Defines the number of simultaneous worker processes.

💡 Pro-Tip for Square: The number of workers depends on your container's plan. Gunicorn's default recommendation is (2 × number of CPU cores) + 1. If your Square plan provides 1 CPU core, configure it to 3 workers to extract maximum concurrency without exceeding the memory limit.

4. Automating the Startup in squarecloud.app

To make all of this work 100% automatically, you just need to map the startup command inside Square's configuration file, squarecloud.app, located at the root of your project.

Add the START directive pointing to the command we structured:

MAIN=wsgi.py
MEMORY=512
VERSION=recommended
START=python -m gunicorn --bind 0.0.0.0:80 --workers 3 wsgi:app

If you prefer to use a separate configuration file for Gunicorn (such as a gunicorn.conf.py for advanced timeout rules or logging), you can simplify the startup line:

START=python -m gunicorn -c gunicorn.conf.py wsgi:app

(Remember that inside your gunicorn.conf.py**, the bind variable must strictly be "0.0.0.0:80").

Updated on: 07/03/2026