Gunicorn with Uvicorn workers in FastAPI - Step-by-Step Execution

Concept Flow - Gunicorn with Uvicorn workers

Start Gunicorn

↓

Gunicorn master process

↓

Spawn Uvicorn worker processes

↓

Each worker runs FastAPI app

↓

Receive HTTP request

↓

Uvicorn worker handles request asynchronously

↓

Send response back

↓

Repeat for next request

Gunicorn starts a master process that spawns multiple Uvicorn workers. Each worker runs the FastAPI app asynchronously to handle incoming HTTP requests concurrently.

Execution Sample

FastAPI

gunicorn -k uvicorn.workers.UvicornWorker main:app --workers 2 --bind 0.0.0.0:8000

This command starts Gunicorn with 2 Uvicorn workers running the FastAPI app defined in main.py as 'app', listening on port 8000.

Execution Table

Step	Process	Action	State Change	Output
1	Gunicorn master	Start master process	Master process running	No direct output
2	Gunicorn master	Spawn Uvicorn worker 1	Worker 1 process running	Ready to handle requests
3	Gunicorn master	Spawn Uvicorn worker 2	Worker 2 process running	Ready to handle requests
4	Client	Send HTTP request	Request arrives at server	Request received by workers
5	Uvicorn worker 1	Accept request	Worker 1 busy handling request	Process request asynchronously
6	Uvicorn worker 1	Send response	Worker 1 free	Response sent to client
7	Client	Send another HTTP request	Request arrives at server	Request received by workers
8	Uvicorn worker 2	Accept request	Worker 2 busy handling request	Process request asynchronously
9	Uvicorn worker 2	Send response	Worker 2 free	Response sent to client
10	Gunicorn master	Monitor workers	Restart worker if crashed	Workers stay available
11	-	No more requests	-	Server waits for new requests

💡 Execution continues indefinitely until server is stopped; workers handle requests concurrently.

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 5	After Step 6	After Step 8	After Step 9	Final
Master process	Not running	Running	Running	Running	Running	Running	Running	Running
Worker 1 process	Not running	Running	Running	Busy	Free	Free	Free	Free
Worker 2 process	Not running	Not running	Running	Running	Running	Busy	Free	Free
Request queue	Empty	Empty	Empty	Empty	Empty	Empty	Empty	Empty

Key Moments - 3 Insights

Why does Gunicorn spawn multiple Uvicorn workers instead of running one?

Gunicorn creates multiple workers to handle many requests at the same time, improving performance and reliability. See steps 2 and 3 in the execution_table where workers are spawned.

How does a Uvicorn worker handle requests asynchronously?

Each Uvicorn worker uses async code to process requests without blocking, allowing it to handle other requests while waiting. This is shown in steps 5 and 8 where workers process requests asynchronously.

What happens if a worker crashes?

Gunicorn master monitors workers and restarts any that crash to keep the server running smoothly, as noted in step 10.

Visual Quiz - 3 Questions

Look at the execution_table at step 5, what is the state of Worker 1?

A Busy handling a request

B Idle and waiting

C Not running

D Restarting

💡 Hint

Check the 'State Change' column at step 5 in the execution_table.

At which step does Gunicorn spawn the second Uvicorn worker?

A Step 2

B Step 3

C Step 4

D Step 5

💡 Hint

Look for 'Spawn Uvicorn worker 2' in the 'Action' column of the execution_table.

If the number of workers is increased to 4, how would the variable_tracker change after step 3?

A Request queue would be empty

B Master process would stop running

C There would be 4 worker processes running instead of 2

D Workers would be busy immediately

💡 Hint

Refer to the 'Worker process' rows in variable_tracker after step 3.

Concept Snapshot

Gunicorn runs a master process that spawns multiple Uvicorn workers.
Each worker runs the FastAPI app asynchronously.
Workers handle HTTP requests concurrently.
Use command: gunicorn -k uvicorn.workers.UvicornWorker main:app --workers N
This setup improves performance and reliability by parallel processing.

Full Transcript

Gunicorn starts by launching a master process. This master process then spawns multiple Uvicorn worker processes. Each worker runs the FastAPI application asynchronously, allowing it to handle HTTP requests without blocking. When a client sends a request, it is received by one of the Uvicorn workers, which processes it and sends back a response. The master process monitors the workers and restarts any that crash to keep the server running smoothly. This setup allows multiple requests to be handled at the same time, improving performance and reliability.

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