How to use the command gunicorn (with examples)

Gunicorn (Green Unicorn) is a Python Web Server Gateway Interface (WSGI) HTTP server. It is designed to be simple, lightweight, and scalable, making it a popular choice for deploying Python web applications.

Use case 1: Run Python web app

Code:

gunicorn import.path:app_object

Motivation:

Running a Python web app using Gunicorn allows you to easily deploy and serve your application over HTTP.

Explanation:

• import.path is the Python import path to the module containing your Flask/Django web application.
• app_object is the name of the Flask/Django application object that Gunicorn should use.

Example output:

[2021-01-01 00:00:00 +0000] [12345] [INFO] Starting gunicorn worker ...
[2021-01-01 00:00:01 +0000] [12345] [INFO] Listening at: http://localhost:8000 (12345)
[2021-01-01 00:00:01 +0000] [12345] [INFO] Using worker: sync
[2021-01-01 00:00:01 +0000] [12345] [INFO] Starting worker process ...

Use case 2: Listen on port 8080 on localhost

Code:

gunicorn --bind localhost:8080 import.path:app_object

Motivation:

Specifying the --bind option allows you to choose the network interface and port on which Gunicorn will listen for incoming connections.

Explanation:

• --bind is used to specify the network interface and port to bind to.
• localhost:8080 tells Gunicorn to bind to the loopback interface (localhost) on port 8080.

Example output:

[2021-01-01 00:00:00 +0000] [12345] [INFO] Starting gunicorn worker ...
[2021-01-01 00:00:01 +0000] [12345] [INFO] Listening at: http://localhost:8080 (12345)
[2021-01-01 00:00:01 +0000] [12345] [INFO] Using worker: sync
[2021-01-01 00:00:01 +0000] [12345] [INFO] Starting worker process ...

Use case 3: Turn on live reload

Code:

gunicorn --reload import.path:app_object

Motivation:

Enabling live reload with the --reload option allows Gunicorn to automatically restart when the code changes, improving the development experience and reducing manual restarts.

Explanation:

• --reload is used to enable live reload functionality.
• When code changes are detected, Gunicorn will automatically restart the worker processes.

Example output:

[2021-01-01 00:00:00 +0000] [12345] [INFO] Starting gunicorn worker ...
[2021-01-01 00:00:01 +0000] [12345] [INFO] Listening at: http://localhost:8000 (12345)
[2021-01-01 00:00:01 +0000] [12345] [INFO] Using worker: sync
[2021-01-01 00:00:01 +0000] [12345] [INFO] Starting worker process ...
[2021-01-01 00:05:00 +0000] [12345] [INFO] Detected change in '/path/to/app.py', restarting worker process ...

Use case 4: Use 4 worker processes for handling requests

Code:

gunicorn --workers 4 import.path:app_object

Motivation:

Increasing the number of worker processes with the --workers option allows Gunicorn to handle multiple requests concurrently, improving the application’s throughput and responsiveness.

Explanation:

• --workers is used to specify the number of worker processes to spawn.
• In this case, Gunicorn will create 4 worker processes to handle incoming requests.

Example output:

[2021-01-01 00:00:00 +0000] [12345] [INFO] Starting gunicorn worker ...
[2021-01-01 00:00:01 +0000] [12345] [INFO] Listening at: http://localhost:8000 (12345)
[2021-01-01 00:00:01 +0000] [12345] [INFO] Using worker: sync
[2021-01-01 00:00:01 +0000] [12345] [INFO] Booting worker with pid: 23456
[2021-01-01 00:00:01 +0000] [12345] [INFO] Booting worker with pid: 23457
[2021-01-01 00:00:01 +0000] [12345] [INFO] Booting worker with pid: 23458
[2021-01-01 00:00:01 +0000] [12345] [INFO] Booting worker with pid: 23459

Use case 5: Use 4 worker threads for handling requests

Code:

gunicorn --threads 4 import.path:app_object

Motivation:

Using worker threads instead of worker processes with the --threads option can be advantageous in certain scenarios, such as when the application is I/O-bound and CPU utilization is not a concern.

Explanation:

• --threads is used to specify the number of worker threads to use.
• In this case, Gunicorn will create 4 worker threads to handle incoming requests.

Example output:

[2021-01-01 00:00:00 +0000] [12345] [INFO] Starting gunicorn worker ...
[2021-01-01 00:00:01 +0000] [12345] [INFO] Listening at: http://localhost:8000 (12345)
[2021-01-01 00:00:01 +0000] [12345] [INFO] Using worker: sync
[2021-01-01 00:00:01 +0000] [12345] [INFO] Booting worker with pid: 23456
[2021-01-01 00:00:01 +0000] [12345] [INFO] Booting worker with pid: 23457
[2021-01-01 00:00:01 +0000] [12345] [INFO] Booting worker with pid: 23458
[2021-01-01 00:00:01 +0000] [12345] [INFO] Booting worker with pid: 23459

Use case 6: Run app over HTTPS

Code:

gunicorn --certfile cert.pem --keyfile key.pem import.path:app_object

Motivation:

Running your Python web app over HTTPS ensures that the communication between the server and clients is encrypted and secure.

Explanation:

• --certfile is used to specify the path to the SSL certificate file.
• --keyfile is used to specify the path to the corresponding SSL private key file.

Example output:

[2021-01-01 00:00:00 +0000] [12345] [INFO] Starting gunicorn worker ...
[2021-01-01 00:00:01 +0000] [12345] [INFO] Listening at: https://localhost:8000 (12345)
[2021-01-01 00:00:01 +0000] [12345] [INFO] Using worker: sync
[2021-01-01 00:00:01 +0000] [12345] [INFO] Starting worker process ...

Conclusion:

Gunicorn is a powerful tool for serving Python web applications. By understanding the various options and use cases, you can effectively configure and deploy your applications with ease. Whether you want to enable live reload, scale the number of worker processes or threads, or secure your application with HTTPS, Gunicorn has you covered. Experiment with different options and find the configuration that best suits your needs. Happy coding!