Getting Started with FastAPI

This chapter takes you from installing FastAPI to running your first API on the development server. Along the way you will look at the API documentation FastAPI generates for you and set up your editor.

Prerequisites

FastAPI is a Python library, so you need Python installed first. Because FastAPI leans heavily on type hints, use a recent Python release within the range the official documentation supports. Check your version in a terminal:

python --version
# On Windows, if the python command is missing
py --version

Create a virtual environment

A virtual environment keeps each project's dependencies separate. Create a project folder, create a .venv environment inside it and activate it.

mkdir hello-fastapi
cd hello-fastapi
python -m venv .venv

# macOS and Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

Once it is active, your prompt shows (.venv) and anything you install with pip stays inside this folder. Run deactivate when you are done.

Install FastAPI

The recommended way to install FastAPI is with the standard extras. They pull in the commonly used dependencies: the Uvicorn ASGI server, the fastapi command-line tool, HTTPX for testing and python-multipart for form handling.

pip install "fastapi[standard]"

Quote the package name, since some shells treat square brackets specially. To pin what you installed, run pip freeze > requirements.txt, then reproduce the same environment elsewhere with pip install -r requirements.txt. Tools such as uv or Poetry work just as well; with them you list dependencies in pyproject.toml.

Write your first API

Create main.py in the project folder:

from fastapi import FastAPI

app = FastAPI()


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


@app.get("/items/{item_id}")
def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}

The app object created by FastAPI() represents your whole application. A function decorated with an HTTP method, such as @app.get("/"), is called a path operation function. Whatever it returns, whether a dict, a list or a Pydantic model, is converted to a JSON response automatically.

In the second function, {item_id} is a path parameter, and the item_id: int annotation tells FastAPI to convert and validate it as an integer. A request to /items/abc never reaches your function: the client gets a 422 response with JSON explaining exactly what was wrong. Because q has a default value, it becomes an optional query parameter such as ?q=hello.

Run the development server

Start the development server with fastapi dev:

fastapi dev main.py

The terminal shows the server address, the docs URL and the app object it found. In development mode the server restarts every time you save a file, and it listens on http://127.0.0.1:8000 by default. Press Ctrl+C to stop it. Add --port 8080 to use another port. Try it from a browser or with curl:

curl http://127.0.0.1:8000/
curl "http://127.0.0.1:8000/items/5?q=hello"

Automatic API docs

FastAPI builds an OpenAPI schema from your code and serves two documentation UIs out of the box:

In /docs, expand an endpoint and click "Try it out" to fill in parameters, send a request and see the response. When you change the code, the docs change with it.

Editor setup

Since FastAPI is driven by type hints, an editor that understands types gives you excellent completion and inline errors.

• VS Code: install Microsoft's Python extension with Pylance, then choose the interpreter inside .venv via "Python: Select Interpreter".
• PyCharm: set .venv as the project interpreter and completion and type checking work for FastAPI code.
• Add Ruff for formatting and linting, and mypy for static type checking.

Summary

• Create a virtual environment and install with pip install "fastapi[standard]".
• Define path operations with a FastAPI() app and decorators such as @app.get.
• Run fastapi dev main.py for a development server that reloads on changes.
• Explore the generated interactive docs at /docs and /redoc.