Tutorial - User Guide¶

This tutorial shows you how to use FastAPI with most of its features, step by step.

Each section gradually builds on the previous ones, but it's structured to separate topics, so that you can go directly to any specific one to solve your specific API needs.

It is also built to work as a future reference so you can come back and see exactly what you need.

Run the code¶

All the code blocks can be copied and used directly (they are actually tested Python files).

To run any of the examples, copy the code to a file main.py, and start fastapi dev with uv run:

$ <font color="#4E9A06">uv run fastapi</font> dev

  <span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span>  Starting development server 🚀

             Searching for package file structure from directories
             with <font color="#3465A4">__init__.py</font> files
             Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>

   <span style="background-color:#007166"><font color="#D3D7CF"> module </font></span>  🐍 main.py

     <span style="background-color:#007166"><font color="#D3D7CF"> code </font></span>  Importing the FastAPI app object from the module with
             the following code:

             <u style="text-decoration-style:solid">from </u><u style="text-decoration-style:solid"><b>main</b></u><u style="text-decoration-style:solid"> import </u><u style="text-decoration-style:solid"><b>app</b></u>

      <span style="background-color:#007166"><font color="#D3D7CF"> app </font></span>  Using import string: <font color="#3465A4">main:app</font>

   <span style="background-color:#007166"><font color="#D3D7CF"> server </font></span>  Server started at <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font>
   <span style="background-color:#007166"><font color="#D3D7CF"> server </font></span>  Documentation at <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000/docs</u></font>

      <span style="background-color:#007166"><font color="#D3D7CF"> tip </font></span>  Running in development mode, for production use:
             <b>fastapi run</b>

             Logs:

     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Will watch for changes in these directories:
             <b>[</b><font color="#4E9A06">&apos;/home/user/code/awesomeapp&apos;</font><b>]</b>
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Uvicorn running on <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font> <b>(</b>Press CTRL+C
             to quit<b>)</b>
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Started reloader process <b>[</b><font color="#34E2E2"><b>383138</b></font><b>]</b> using WatchFiles
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Started server process <b>[</b><font color="#34E2E2"><b>383153</b></font><b>]</b>
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Waiting for application startup.
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Application startup complete.

It is HIGHLY encouraged that you write or copy the code, edit it and run it locally.

Using it in your editor is what really shows you the benefits of FastAPI, seeing how little code you have to write, all the type checks, autocompletion, etc.

Install FastAPI¶

The first step is to set up your project and add FastAPI.

Install uv, then create a project and add FastAPI:

$ uv init awesome-project --bare
$ cd awesome-project
$ uv add "fastapi[standard]"

---> 100%

uv add creates the project's virtual environment in .venv, adds FastAPI to pyproject.toml, and creates uv.lock so the same package versions can be installed later.

What these commands do

uv init: create a new Python project.
awesome-project: create the project in a new directory with this name.
--bare: create only the minimal pyproject.toml file, without generating a sample main.py, README.md, or other files. You will create the application files yourself in the next steps of this tutorial.

Then cd awesome-project enters the new project directory before adding FastAPI.

uv will use a compatible Python version already installed on your system, or download one if needed.

When you run uv add, it selects compatible versions of FastAPI and all the packages FastAPI depends on. It records the exact versions in uv.lock, making it possible to install the same package versions later on another computer or when deploying the application.

Creating or updating this file is called locking the project dependencies. uv does this automatically when you add a package.

FastAPI installation options

When you install with uv add "fastapi[standard]" it comes with some default optional standard dependencies, including fastapi-cloud-cli, which allows you to deploy to FastAPI Cloud.

If you don't want to have those optional dependencies, you can instead install uv add fastapi.

If you want to install the standard dependencies but without the fastapi-cloud-cli, you can install with uv add "fastapi[standard-no-fastapi-cloud-cli]".

Using pip instead

If you prefer to manage a virtual environment and packages manually, create and activate a virtual environment and then install FastAPI with pip install "fastapi[standard]".

Read the Virtual Environments guide for the detailed steps.

AI Agent Skills¶

FastAPI includes an official skill for AI coding agents. It is bundled with the package, so its guidance stays aligned with the version of FastAPI installed in your project and updates when you update FastAPI.

After installing FastAPI in your project, you can install the skill with Library Skills:

uvx library-skills

Note

uvx is an alias for uv tool run. It runs Library Skills in a temporary, isolated environment while Library Skills scans the packages installed in your project.

The skill is compatible with Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Pi, OpenCode, and most other coding agents. For Claude Code, select .claude/skills when asked where to install the skill.

Advanced User Guide¶

There is also an Advanced User Guide that you can read later after this Tutorial - User Guide.

The Advanced User Guide builds on this one, uses the same concepts, and teaches you some extra features.

But you should first read the Tutorial - User Guide (what you are reading right now).

It's designed so that you can build a complete application with just the Tutorial - User Guide, and then extend it in different ways, depending on your needs, using some of the additional ideas from the Advanced User Guide.