Uvicorn server basics in FastAPI - Step-by-Step Execution

Concept Flow - Uvicorn server basics

Write FastAPI app code

↓

Run Uvicorn server command

↓

Uvicorn loads app

↓

Server listens on host:port

↓

Client sends HTTP request

↓

Uvicorn routes request to FastAPI app

↓

App processes request and returns response

↓

Uvicorn sends response back to client

↓

Repeat for next requests or stop server

This flow shows how you write a FastAPI app, run it with Uvicorn, and how Uvicorn handles requests and responses.

Execution Sample

FastAPI

from fastapi import FastAPI
import uvicorn

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello World"}

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8000)

This code creates a simple FastAPI app and runs it with Uvicorn on localhost port 8000.

Execution Table

Step	Action	Evaluation	Result
1	Import FastAPI and Uvicorn	Modules loaded	Ready to create app
2	Create FastAPI app instance	app = FastAPI()	App object created
3	Define GET endpoint '/'	Function read_root registered	Endpoint ready
4	Check if __name__ == '__main__'	True when run directly	Proceed to run server
5	Call uvicorn.run(app, host, port)	Uvicorn starts server	Server listens on 127.0.0.1:8000
6	Client sends GET request to '/'	Uvicorn receives request	Routes to read_root function
7	read_root executes	Returns {'message': 'Hello World'}	Response prepared
8	Uvicorn sends response to client	Client receives JSON message	Request complete
9	Wait for next request or stop	Server running	Loop continues or server stops

💡 Server stops when process is terminated or interrupted

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 5	After Step 7	Final
app	undefined	FastAPI instance	FastAPI with endpoint	Running server reference	N/A	N/A
read_root	undefined	undefined	Function registered	N/A	Function executed	N/A

Key Moments - 3 Insights

Why do we check if __name__ == '__main__' before running uvicorn?

This check ensures the server runs only when the script is executed directly, not when imported. See execution_table step 4.

What happens if the client sends a request to a path not defined in the app?

Uvicorn returns a 404 Not Found response because no matching endpoint exists. This is part of Uvicorn routing after step 6.

Why is the read_root function defined as async?

FastAPI supports async functions for better performance with I/O. Uvicorn can handle async endpoints efficiently, as shown in step 7.

Visual Quiz - 3 Questions

Look at the execution_table, what is the result after step 5?

A App object created

B Server listens on 127.0.0.1:8000

C Function read_root registered

D Client receives JSON message

💡 Hint

Check the 'Result' column for step 5 in execution_table

At which step does the server send the response back to the client?

A Step 8

B Step 7

C Step 6

D Step 9

💡 Hint

Look for 'Uvicorn sends response to client' in execution_table

If we remove the if __name__ == '__main__' check, what changes in the execution?

A App object is not created

B Endpoints are not registered

C Server runs even when imported as a module

D Client requests fail

💡 Hint

Refer to key_moments about the purpose of the __name__ check

Concept Snapshot

Uvicorn runs FastAPI apps by loading the app instance and listening on a host and port.
Use uvicorn.run(app, host, port) inside if __name__ == '__main__' to start the server.
Uvicorn routes HTTP requests to FastAPI endpoints and sends back responses.
Async functions in FastAPI improve performance with Uvicorn.
Stop the server by interrupting the process (Ctrl+C).

Full Transcript

This visual execution shows how a FastAPI app is created and run using Uvicorn. First, the FastAPI app instance is created and endpoints are defined. Then, the script checks if it is run directly and starts the Uvicorn server on localhost port 8000. When a client sends a request, Uvicorn receives it and routes it to the matching FastAPI endpoint function. The function executes asynchronously and returns a JSON response. Uvicorn sends this response back to the client. The server keeps running until stopped. Key points include the importance of the __name__ check to avoid running the server on import, and how Uvicorn handles async endpoints efficiently.

Practice

1. What is the main purpose of running uvicorn with a FastAPI app?

easy

A. To start a server that handles web requests for the FastAPI app

B. To compile the FastAPI app into an executable file

C. To create a database connection for the FastAPI app

D. To generate API documentation automatically

Solution

1. Step 1: Understand what Uvicorn does

   Uvicorn is an ASGI server that runs your FastAPI app so it can receive and respond to web requests.

2. Step 2: Identify the purpose of running Uvicorn

   Running Uvicorn starts the server that listens for HTTP requests and sends responses from your FastAPI app.

3. Final Answer:

   To start a server that handles web requests for the FastAPI app -> Option A

4. Quick Check:

   Uvicorn runs server = A [OK]

Hint: Remember: Uvicorn runs the server for your app [OK]

Common Mistakes:

• Thinking Uvicorn compiles code
• Confusing server start with database setup
• Assuming Uvicorn generates docs automatically

2. Which of the following is the correct command to run a FastAPI app located in main.py with auto-reload enabled?

easy

A. uvicorn main:app reload

B. uvicorn main:app --reload

C. uvicorn app:main --reload

D. uvicorn main.py --reload

Solution

1. Step 1: Understand Uvicorn command syntax

   The correct syntax is uvicorn module_name:app_variable. Here, the module is main and the app variable is app.

2. Step 2: Check the options for auto-reload

   The option --reload enables auto-reload during development.

3. Final Answer:

   uvicorn main:app --reload -> Option B

4. Quick Check:

   Correct syntax with --reload = D [OK]

Hint: Use module:app format with --reload flag [OK]

Common Mistakes:

• Including .py extension in module name
• Swapping module and app names
• Missing double dashes before reload

3. Given this command: uvicorn app.main:app --host 0.0.0.0 --port 8080, what will be the effect?

medium

A. The app runs on localhost at port 80

B. The app runs only on 127.0.0.1 at port 8080

C. The app runs on all network interfaces at port 8080

D. The app runs on all interfaces at default port 8000

Solution

1. Step 1: Analyze the host option

   The host 0.0.0.0 means the server listens on all network interfaces, not just localhost.

2. Step 2: Analyze the port option

   The port is explicitly set to 8080, so the app will listen on port 8080.

3. Final Answer:

   The app runs on all network interfaces at port 8080 -> Option C

4. Quick Check:

   Host 0.0.0.0 + port 8080 = C [OK]

Hint: 0.0.0.0 means all interfaces, port sets listening port [OK]

Common Mistakes:

• Assuming 0.0.0.0 means localhost only
• Ignoring the port option
• Confusing default port 8000 with specified port

4. You run uvicorn main:app --reload but get an error: ModuleNotFoundError: No module named 'main'. What is the likely cause?

medium

A. The app variable is not named app inside main.py

B. Uvicorn requires Python 2, but you have Python 3

C. The --reload flag is not supported on your system

D. The file main.py is missing or not in the current directory

Solution

1. Step 1: Understand the error message

   The error says the module main cannot be found, meaning Python can't locate main.py.

2. Step 2: Check file location

   If main.py is missing or not in the current directory where the command runs, this error occurs.

3. Final Answer:

   The file main.py is missing or not in the current directory -> Option D

4. Quick Check:

   ModuleNotFoundError means missing file/module = B [OK]

Hint: Check if main.py exists in current folder [OK]

Common Mistakes:

• Assuming app variable name causes ModuleNotFoundError
• Blaming --reload flag for module errors
• Confusing Python version requirements

5. You want to run your FastAPI app with Uvicorn so it reloads on code changes and listens only on localhost at port 5000. Which command is correct?

hard

A. uvicorn app:app --reload --host 127.0.0.1 --port 5000

B. uvicorn app:app --reload --host 0.0.0.0 --port 5000

C. uvicorn app:app --host 127.0.0.1 --port 5000

D. uvicorn app:app --reload --port 127.0.0.1 --host 5000

Solution

1. Step 1: Identify the reload option

   The --reload flag enables auto-reload on code changes, so it must be included.

2. Step 2: Set host and port correctly

   Listening only on localhost means host should be 127.0.0.1. The port must be set to 5000 using --port 5000.

3. Step 3: Check option order and syntax

   Options order does not affect functionality, but the syntax must be correct: --host followed by IP, --port followed by port number.

4. Final Answer:

   uvicorn app:app --reload --host 127.0.0.1 --port 5000 -> Option A

5. Quick Check:

   Reload + localhost + port 5000 = A [OK]

Hint: Use --reload with --host 127.0.0.1 and --port 5000 [OK]

Common Mistakes:

• Using 0.0.0.0 for localhost only
• Swapping host and port values
• Omitting --reload for auto-reload