David's Blog

Running Python Web Applications with Gunicorn

By David Li on 2024-08-25T10:07:00.000Z

Running Python Web Applications with Gunicorn

Gunicorn, or Green Unicorn, is a Python Web Server Gateway Interface (WSGI) HTTP server. It is a pre-fork worker model, which means it forks multiple worker processes to handle incoming requests. Gunicorn is often used to serve Python web applications behind a reverse proxy, such as Nginx or Apache, providing a reliable and efficient way to deploy web applications. In this article, we will discuss the basics of Gunicorn, how to install and configure it, and how to use it to serve a Python web application.


To follow along with this tutorial, you should have:

  • Basic knowledge of Python and web applications.
  • Python 3.6 or higher installed on your system.
  • A Python web application to serve (we will use a simple Flask application as an example).


You can install Gunicorn using pip, the Python package manager. Run the following command to install Gunicorn:

pip install gunicorn

Make sure to activate your virtual environment if you are using one before running the command.

Running a Simple Flask Application with Gunicorn

For this tutorial, we will use a simple Flask application as an example. If you don’t have Flask installed, you can install it using pip:

pip install Flask

Now, create a new file called app.py and add the following code to create a basic Flask application:

from flask import Flask

app = Flask(__name__)

def hello_world():
    return 'Hello, Gunicorn!'

if __name__ == '__main__':

To run this application with Gunicorn, navigate to the directory containing app.py and run the following command:

gunicorn app:app

This command tells Gunicorn to run the app object from the app module. By default, Gunicorn will start one worker process and bind to localhost on port 8000. You can now visit http://localhost:8000 in your web browser to see the “Hello, Gunicorn!” message.

Configuring Gunicorn

Gunicorn provides several configuration options to customize its behavior. You can specify these options using command-line arguments or a configuration file.

Command-Line Arguments

Here are some common command-line arguments you can use to configure Gunicorn:

  • --workers: The number of worker processes. It is recommended to set this value to the number of available CPU cores.
  • --bind: The address and port to bind Gunicorn to. For example, --bind will bind Gunicorn to all available network interfaces on port 8080.
  • --timeout: The maximum time (in seconds) a worker can take to process a request before being killed and restarted. The default is 30 seconds.
  • --log-level: The logging level. Possible values are debug, info, warning, error, and critical. The default is info.

For example, to run Gunicorn with four worker processes and bind it to all available network interfaces on port 8080, you can run:

gunicorn app:app --workers 4 --bind

Configuration File

You can also use a configuration file to specify Gunicorn’s settings. Create a new file called gunicorn.conf.py in the same directory as your app.py file and add the following contents:

workers = 4
bind = ""
timeout = 30
loglevel = "info"

Now, you can run Gunicorn with the configuration file using the following command:

gunicorn app:app -c gunicorn.conf.py

Deploying with a Reverse Proxy

In a production environment, it is recommended to use a reverse proxy, such as Nginx or Apache, to handle incoming requests and forward them to Gunicorn. This provides better performance, security, and flexibility.

Here is a sample Nginx configuration to proxy requests to a Gunicorn server running on localhost:8080:

http {
    server {
        listen 80;

        location / {
            proxy_pass http://localhost:8080;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Now, you can run your Gunicorn server with the desired configuration, and Nginx will handle incoming requests and forward them to Gunicorn.


In this article, we have discussed the basics of Gunicorn, a popular WSGI server for Python web applications. We have covered installation, configuration, and deploymentoptions for Gunicorn, including using command-line arguments and a configuration file. Finally, we demonstrated how to deploy a Python web application using Gunicorn and a reverse proxy like Nginx.

Gunicorn is a powerful and flexible tool for deploying Python web applications, providing a reliable and efficient way to serve your applications to users. By understanding the basics and utilizing Gunicorn’s configuration options, you can ensure that your web applications run smoothly and securely in a production environment.

© Copyright 2023 by Astro Tech Blog. Built with ♥ by FriendlyUser. Last updated on 2023-12-07.