Install Gunicorn in Python Guide

Gunicorn is a popular WSGI HTTP server for Python web applications. It helps you run your Flask or Django apps in production. This guide shows you how to install Gunicorn in Python quickly and correctly.

We will cover installation, verification, and basic usage. Each step includes clear commands and examples. Beginners will find this easy to follow.

What is Gunicorn?

Gunicorn stands for Green Unicorn. It is a Python WSGI HTTP server. It runs your web application and handles multiple requests at once.

Gunicorn works with frameworks like Flask, Django, and Pyramid. It is fast, stable, and easy to configure. Many production systems use Gunicorn behind a reverse proxy like Nginx.

You install Gunicorn using pip, the Python package manager. It works on Linux, macOS, and Windows (with some limitations).

Prerequisites

Before installing Gunicorn, ensure you have Python installed. Check your Python version with this command:

python --version

You should see Python 3.6 or higher. Also, install pip if you do not have it. Use this command to check pip:

pip --version

If pip is missing, install it from the official Python website. Using a virtual environment is recommended for clean project isolation.

Step 1: Create a Virtual Environment

A virtual environment keeps your project dependencies separate. Create one with these commands:

python -m venv myenv
source myenv/bin/activate   # On Linux/macOS
myenv\Scripts\activate      # On Windows

Your terminal prompt will change to show the environment name. This means you are inside the virtual environment.

Step 2: Install Gunicorn Using pip

Now install Gunicorn. The command is simple:

pip install gunicorn

This downloads and installs Gunicorn and its dependencies. Wait a few seconds for the process to finish.

You can also install a specific version if needed:

pip install gunicorn==20.1.0

Check the official PyPI page for the latest stable version. Always use a recent release for security and features.

Step 3: Verify the Installation

Confirm Gunicorn is installed correctly. Run this command:

gunicorn --version

You should see output like this:

gunicorn (version 20.1.0)

If you see an error, check your PATH or virtual environment activation. Ensure pip is updated:

pip install --upgrade pip

Step 4: Create a Simple Flask App

To test Gunicorn, create a minimal Flask application. Save this code as app.py:

 
from flask import Flask

app = Flask(__name__)

@app.route('/')
def home():
    return "Hello, Gunicorn!"

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

This app returns a simple message. Install Flask first if you do not have it:

pip install flask

Step 5: Run Your App with Gunicorn

Now use Gunicorn to serve your Flask app. The basic command is:

gunicorn app:app

Here, app:app means module name (app.py) and Flask instance name (app). Gunicorn starts and listens on port 8000 by default.

You will see output like this:

[INFO] Starting gunicorn 20.1.0
[INFO] Listening at: http://127.0.0.1:8000
[INFO] Using worker: sync
[INFO] Booting worker with pid: 12345

Open your browser and visit http://127.0.0.1:8000. You will see "Hello, Gunicorn!"

Step 6: Customize Gunicorn Options

Gunicorn offers many options for production use. Common flags include:

• --workers – Number of worker processes
• --bind – Bind to a specific IP and port
• --log-level – Set logging verbosity

Example with 4 workers on port 8080:

gunicorn --workers 4 --bind 0.0.0.0:8080 app:app

This makes your app accessible on your network. For production, use a reverse proxy like Nginx for security.

Step 7: Install Gunicorn in a Requirements File

For reproducible deployments, add Gunicorn to a requirements.txt file. Create this file with one line:

gunicorn==20.1.0

Then install all dependencies at once:

pip install -r requirements.txt

This ensures everyone uses the same version. It is a best practice for team projects.

Common Installation Issues

Sometimes installation fails. Here are solutions:

Permission denied – Use a virtual environment or add --user flag:

pip install --user gunicorn

Command not found – Ensure your virtual environment is active. Check with which gunicorn on Linux/macOS.

Windows compatibility – Gunicorn works best on Unix-like systems. On Windows, consider using WSL or a Linux VM for production.

Testing with a Django App

Gunicorn also works with Django. First, install Django and create a project. Then run:

gunicorn myproject.wsgi:application

Replace myproject with your Django project name. The wsgi.py file contains the WSGI application object.

Conclusion

Installing Gunicorn in Python is straightforward. You created a virtual environment, installed Gunicorn with pip, and tested it with a Flask app. You also learned custom options and troubleshooting tips.

Gunicorn is a key tool for deploying Python web apps. It handles concurrent requests efficiently. Use it with a reverse proxy like Nginx for production readiness.

Now you can deploy your own applications confidently. Start small, test locally, then move to a server. Happy coding!