[FastAPI Series 2] Getting Started: Install and Run Your First API

Learning FastAPI works best when you launch a real server early. FastAPI turns Python functions into HTTP APIs. uv bootstraps the project folder and manages dependencies. uvicorn binds the FastAPI app to HTTP. Holding onto the "focus on the core flow" rule from part 1, this post stays with installation and the very first run so later posts can jump straight to parameters. If uv is new to you, install it from the official instructions or fall back to pip + python -m venv; the rest of the steps translate directly.

Key terms

1. uv – a lightweight package/environment manager (think "pip + virtualenv" in one tool) that initializes Python projects and runs commands. Every command in this post uses it.
2. ASGI – the async server interface standard that lets uvicorn run FastAPI apps.
3. Swagger UI – the automatically generated API docs at /docs once FastAPI is running.

Practice card

• Estimated time: 30 minutes
• Prereqs: Python 3.12, uv installed, VS Code or any terminal
• Goal: create a FastAPI project with uv and start the dev server

This walkthrough targets FastAPI ≥ 0.111 (for the built-in CLI) and uv ≥ 0.2.0. If you prefer pip, just replace uv add ... with pip install ... and run commands inside your virtualenv by prefixing them with python -m or uvicorn directly.

Getting started checklist

• Start a FastAPI project with uv
• Create the simplest API file
• Check both the JSON response and the docs page in a browser

Setup

Assuming uv is already installed (uv --version should print a version number), create a project folder.

uv init my-fastapi-app
cd my-fastapi-app

Install packages

uv add fastapi --extra standard

The --extra standard bundle installs FastAPI, uvicorn, and helpful dev dependencies (such as the docs stack). If you skip the extra, add uvicorn manually with uv add uvicorn so the server command works later.

What uvicorn does

Keep the roles straight:

• FastAPI defines endpoints and validation rules.
• uvicorn is the ASGI server that exposes those endpoints over HTTP.

Think of ASGI as the handshake async Python web servers follow. When the browser makes a request, the flow looks like this:

Browser -> uvicorn -> FastAPI app -> JSON response

If that still feels abstract, this diagram is enough for now:

Having app = FastAPI() in main.py is not enough. You still need a server that opens a port, listens for requests, and calls that app. uvicorn is the engine that does exactly that. Even when you run uv run fastapi dev main.py, the logs say Uvicorn running on ... because that command wraps a uvicorn dev server under the hood. If your reader does not render D2 diagrams, picture the same flow as plain text: the browser sends an HTTP request to uvicorn, uvicorn invokes your FastAPI app, the app returns a dict/list, and uvicorn sends that JSON back to the browser.

Build the first app

Create main.py.

from fastapi import FastAPI

app = FastAPI()

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

@app.get("/items")
def read_items():
    return [
        {"id": 1, "name": "Pencil"},
        {"id": 2, "name": "Notebook"},
    ]

Flow recap:

• Instantiate the app with FastAPI().
• Register routes with @app.get(...).
• If you return built-in types such as dict or list, FastAPI serializes them to JSON automatically (you can customize this later with response classes).

Run the dev server

uv run fastapi dev main.py

Breakdown:

• uv run – execute within the project environment.
• fastapi dev – start the FastAPI dev server (uses uvicorn beneath).
• main.py – file containing the app.

When it succeeds you should see something like:

INFO:     Uvicorn running on http://127.0.0.1:8000

Heads-up: fastapi dev ships with FastAPI 0.111+. If the CLI is unavailable, run uv run uvicorn main:app --reload instead.

Verify in the browser

Basic response

Open http://127.0.0.1:8000/ to see:

{"message":"Hello FastAPI"}

Docs pages

FastAPI also gives you docs instantly:

• http://127.0.0.1:8000/docs
• http://127.0.0.1:8000/redoc

In /docs you can press buttons to send actual requests.

{"message":"Hello FastAPI"}

[{"id":1,"name":"Pencil"},{"id":2,"name":"Notebook"}]

Check from the CLI

Many club automations or monitoring scripts hit APIs from the CLI. You can use curl (already installed on macOS/Linux) or install httpx. To follow along with httpx, run:

uv add httpx
uv run python -m httpx http://127.0.0.1:8000/items

Either tool should return the same JSON list of objects shown earlier.

Common confusion

If you hit errors such as command not found or ModuleNotFoundError: fastapi, double-check that you ran uv add fastapi --extra standard inside the project folder and that every command begins with uv run ... so it executes in the managed environment.

Why not python main.py?

FastAPI apps live behind a web server. You need something to import the app, bind to a port, and handle HTTP. uvicorn does that job, and uv run fastapi dev main.py is a friendly wrapper.

You can also run it explicitly:

uv run uvicorn main:app --reload

fastapi dev is great for beginners, and the uvicorn command helps you understand the structure later. The --reload flag watches your files and restarts the dev server automatically—handy locally, but turn it off in production.

Port already in use?

Pick another port.

uv run fastapi dev main.py --port 8001

Minimum goals today

• Run uv add fastapi --extra standard.
• Define the first routes in main.py.
• Start the server with uv run fastapi dev main.py.
• Visit / and /docs.

Practice

• Follow along: run uv run fastapi dev main.py and check / plus /items.
• Extend: add /items/{item_id} (e.g., @app.get("/items/{item_id}") returning a single object) and call it from Swagger UI.
• Debug: if the port is taken, solve it with --port 8001.
• Done when: both routes return 200 and /docs's Try it out button works.

Wrap-up

The big lesson is that FastAPI wires a function directly to HTTP. Once you see JSON in a browser, the upcoming work on path parameters or request bodies feels far less intimidating.

Remember that both fastapi dev and uvicorn --reload are development servers; switch to a production ASGI server (uvicorn without --reload, hypercorn, etc.) and proper process manager when you deploy.

Next up: expanding GET requests with path and query parameters.