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.