Gunicorn with Uvicorn workers in FastAPI - Mini Project: Build & Apply

Gunicorn with Uvicorn Workers for FastAPI

📖 Scenario: You want to deploy a FastAPI application using Gunicorn as the process manager and Uvicorn as the worker class. This setup helps handle multiple requests efficiently in a production environment.

🎯 Goal: Create a FastAPI app, configure Gunicorn to use Uvicorn workers, and run the app with this configuration.

📋 What You'll Learn

Create a FastAPI app instance named app with a root endpoint returning a JSON message

Define a Gunicorn configuration variable workers set to 2

Use the Gunicorn command line to specify uvicorn.workers.UvicornWorker as the worker class

Run the FastAPI app with Gunicorn using the Uvicorn worker class and the specified number of workers

💡 Why This Matters

🌍 Real World

Deploying FastAPI apps in production requires a robust server setup. Gunicorn manages multiple worker processes, and Uvicorn provides asynchronous workers optimized for FastAPI.

💼 Career

Understanding how to deploy FastAPI with Gunicorn and Uvicorn is essential for backend developers working on scalable web services.

1

Create a FastAPI app with a root endpoint

Write code to import FastAPI, create an app instance named app, and add a root endpoint / that returns a JSON dictionary with {"message": "Hello, Gunicorn with Uvicorn!"}.

FastAPI

# Your code here

Hint

Start by importing FastAPI, then create app = FastAPI(). Use @app.get("/") to define the root route that returns the JSON message.

2

Set Gunicorn worker count configuration

Add a variable named workers and set it to 2 to configure Gunicorn to use two worker processes.

FastAPI

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello, Gunicorn with Uvicorn!"}

# Define number of Gunicorn workers
# Your code here

Hint

Simply create a variable workers and assign it the value 2.

3

Use Gunicorn with Uvicorn worker class in command

Write the Gunicorn command to run the FastAPI app with the Uvicorn worker class. Use the app module name main and the app instance app. Include the --workers 2 option and specify the worker class as uvicorn.workers.UvicornWorker.

FastAPI

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello, Gunicorn with Uvicorn!"}

workers = 2

# Write the Gunicorn command below
# Your code here

Hint

Use the command format: gunicorn main:app --workers 2 --worker-class uvicorn.workers.UvicornWorker.

4

Run the FastAPI app with Gunicorn and Uvicorn workers

Add a comment line showing how to run the FastAPI app using Gunicorn with the Uvicorn worker class and the workers variable. Use the command format: gunicorn main:app --workers 2 --worker-class uvicorn.workers.UvicornWorker.

FastAPI

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello, Gunicorn with Uvicorn!"}

workers = 2

# Command to run:
# gunicorn main:app --workers 2 --worker-class uvicorn.workers.UvicornWorker

# Your code here

Hint

Just add a comment line with the full Gunicorn command to run the app with Uvicorn workers.

Practice

1. What is the main reason to use Gunicorn with Uvicorn workers when running a FastAPI app?

easy

A. To convert FastAPI apps into desktop applications

B. To run FastAPI apps only in development mode

C. To automatically generate API documentation

D. To efficiently handle multiple requests asynchronously in production

Solution

1. Step 1: Understand Gunicorn and Uvicorn roles

   Gunicorn is a production server that manages multiple worker processes. Uvicorn is an async server that runs FastAPI apps efficiently.

2. Step 2: Combine Gunicorn with Uvicorn workers

   Using Gunicorn with Uvicorn workers allows handling many requests asynchronously and improves performance in production.

3. Final Answer:

   To efficiently handle multiple requests asynchronously in production -> Option D

4. Quick Check:

   Gunicorn + Uvicorn = async production efficiency [OK]

Hint: Gunicorn manages workers; Uvicorn handles async FastAPI [OK]

Common Mistakes:

• Thinking Gunicorn is only for development
• Confusing Uvicorn with API documentation tools
• Believing this setup creates desktop apps

2. Which of the following is the correct command to start a FastAPI app with 4 Uvicorn workers using Gunicorn?

easy

A. gunicorn -k uvicorn.workers.UvicornWorker -w main:app 4

B. uvicorn -w 4 -k gunicorn.workers.GunicornWorker main:app

C. gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app

D. uvicorn main:app -w 4 -k gunicorn.workers.GunicornWorker

Solution

1. Step 1: Identify Gunicorn command syntax

   Gunicorn uses '-w' to set workers and '-k' to specify worker class.

2. Step 2: Match correct worker class and app reference

   Uvicorn worker class is 'uvicorn.workers.UvicornWorker' and app is referenced as 'main:app'.

3. Final Answer:

   gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app -> Option C

4. Quick Check:

   Gunicorn -w 4 -k UvicornWorker main:app [OK]

Hint: Gunicorn uses -w for workers and -k for worker class [OK]

Common Mistakes:

• Using uvicorn command instead of gunicorn
• Swapping worker class names incorrectly
• Placing worker count after app name

3. Given this command: gunicorn -w 3 -k uvicorn.workers.UvicornWorker main:app, what will happen when the FastAPI app receives multiple simultaneous requests?

medium

A. Requests will be handled concurrently by 3 async workers improving throughput

B. Only one request will be handled at a time, others will wait

C. The app will crash because Gunicorn cannot run async workers

D. Requests will be queued but processed sequentially by a single worker

Solution

1. Step 1: Understand worker count and async support

   Gunicorn runs 3 workers, each using Uvicorn's async worker class to handle requests asynchronously.

2. Step 2: Effect on request handling

   Multiple requests can be handled concurrently by these 3 async workers, improving throughput and responsiveness.

3. Final Answer:

   Requests will be handled concurrently by 3 async workers improving throughput -> Option A

4. Quick Check:

   3 async workers = concurrent request handling [OK]

Hint: More workers + async = better concurrent handling [OK]

Common Mistakes:

• Assuming only one request at a time
• Thinking Gunicorn can't run async workers
• Believing requests queue without concurrency

4. You run gunicorn -w 2 -k uvicorn.workers.UvicornWorker app:app but get an error: ModuleNotFoundError: No module named 'uvicorn'. What is the likely cause?

medium

A. Uvicorn is not installed in the environment

B. Gunicorn does not support the -k option

C. The app module is missing

D. The worker count -w must be at least 4

Solution

1. Step 1: Analyze the error message

   The error says 'No module named uvicorn', indicating Python cannot find the uvicorn package.

2. Step 2: Check environment setup

   This usually means uvicorn is not installed in the current Python environment where Gunicorn runs.

3. Final Answer:

   Uvicorn is not installed in the environment -> Option A

4. Quick Check:

   Missing uvicorn package causes ModuleNotFoundError [OK]

Hint: Install uvicorn package to fix ModuleNotFoundError [OK]

Common Mistakes:

• Assuming Gunicorn lacks -k support
• Blaming app module instead of missing package
• Thinking worker count causes import errors

5. You want to deploy a FastAPI app with Gunicorn and Uvicorn workers on a server with 8 CPU cores. Which command best balances performance and resource use?

hard

A. gunicorn -w 8 -k uvicorn.workers.UvicornWorker main:app

B. gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app

C. gunicorn -w 16 -k uvicorn.workers.UvicornWorker main:app

D. gunicorn -w 1 -k uvicorn.workers.UvicornWorker main:app

Solution

1. Step 1: Understand worker count vs CPU cores

   Best practice is to use a moderate number of workers (such as 4) for async apps, but too many workers can cause overhead.

2. Step 2: Choose balanced worker count

   Using 4 workers on 8 cores balances concurrency and resource use without excessive context switching.

3. Final Answer:

   gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app -> Option B

4. Quick Check:

   4 workers on 8 cores = balanced performance [OK]

Hint: Use fewer workers than CPU cores for async apps [OK]

Common Mistakes:

• Using too many workers causing overhead
• Using only one worker limiting concurrency
• Matching workers exactly to CPU cores without buffer