docs/en/docs/advanced/settings.md::Settings in a dependency { #settings-in-a-dependency }::L119

# Doc: docs/en/docs/advanced/settings.md | Page: Settings and Environment Variables { #settings-and-environment-variables } | Section: Settings in a dependency { #settings-in-a-dependency }
## Settings in a dependency { #settings-in-a-dependency }

In some occasions it might be useful to provide the settings from a dependency, instead of having a global object with `settings` that is used everywhere.

This could be especially useful during testing, as it's very easy to override a dependency with your own custom settings.

### The config file { #the-config-file }

Coming from the previous example, your `config.py` file could look like:

{* ../../docs_src/settings/app02_an_py310/config.py hl[10] *}

Notice that now we don't create a default instance `settings = Settings()`.

### The main app file { #the-main-app-file }

Now we create a dependency that returns a new `config.Settings()`.

{* ../../docs_src/settings/app02_an_py310/main.py hl[6,12:13] *}

/// tip

We'll discuss the `@lru_cache` in a bit.

For now you can assume `get_settings()` is a normal function.

///

And then we can require it from the *path operation function* as a dependency and use it anywhere we need it.

{* ../../docs_src/settings/app02_an_py310/main.py hl[17,19:21] *}

### Settings and testing { #settings-and-testing }

Then it would be very easy to provide a different settings object during testing by creating a dependency override for `get_settings`:

{* ../../docs_src/settings/app02_an_py310/test_main.py hl[9:10,13,21] *}

In the dependency override we set a new value for the `admin_email` when creating the new `Settings` object, and then we return that new object.

Then we can test that it is used.


docs/en/docs/advanced/settings.md::Reading a `.env` file { #reading-a-env-file }::L161

# Doc: docs/en/docs/advanced/settings.md | Page: Settings and Environment Variables { #settings-and-environment-variables } | Section: Reading a `.env` file { #reading-a-env-file }
## Reading a `.env` file { #reading-a-env-file }

If you have many settings that possibly change a lot, maybe in different environments, it might be useful to put them on a file and then read them from it as if they were environment variables.

This practice is common enough that it has a name, these environment variables are commonly placed in a file `.env`, and the file is called a "dotenv".

/// tip

A file starting with a dot (`.`) is a hidden file in Unix-like systems, like Linux and macOS.

But a dotenv file doesn't really have to have that exact filename.

///

Pydantic has support for reading from these types of files using an external library. You can read more at [Pydantic Settings: Dotenv (.env) support](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support).

/// tip

For this to work, you need to `pip install python-dotenv`.

///

### The `.env` file { #the-env-file }

You could have a `.env` file with:

```bash
ADMIN_EMAIL="deadpool@example.com"
APP_NAME="ChimichangApp"
```

### Read settings from `.env` { #read-settings-from-env }

And then update your `config.py` with:

{* ../../docs_src/settings/app03_an_py310/config.py hl[9] *}

/// tip

The `model_config` attribute is used just for Pydantic configuration. You can read more at [Pydantic: Concepts: Configuration](https://docs.pydantic.dev/latest/concepts/config/).

///

Here we define the config `env_file` inside of your Pydantic `Settings` class, and set the value to the filename with the dotenv file we want to use.

### Creating the `Settings` only once with `lru_cache` { #creating-the-settings-only-once-with-lru-cache }

Reading a file from disk is normally a costly (slow) operation, so you probably want to do it only once and then reuse the same settings object, instead of reading it for each request.

But every time we do:

```Python
Settings()
```

a new `Settings` object would be created, and at creation it would read the `.env` file again.

If the dependency function was just like:

```Python
def get_settings():
    return Settings()
```

we would create that object for each request, and we would be reading the `.env` file for each request. ⚠

But as we are using the `@lru_cache` decorator on top, the `Settings` object will be created only once, the first time it's called. ✔

{* ../../docs_src/settings/app03_an_py310/main.py hl[1,11] *}

Then for any subsequent call of `get_settings()` in the dependencies for the next requests, instead of executing the internal code of `get_settings()` and creating a new `Settings` object, it will return the same object that was returned on the first call, again and again.

#### `lru_cache` Technical Details { #lru-cache-technical-details }

`@lru_cache` modifies the function it decorates to return the same value that was returned the first time, instead of computing it again, executing the code of the function every time.

So, the function below it will be executed once for each combination of arguments. And then the values returned by each of those combinations of arguments will be used again and again whenever the function is called with exactly the same combination of arguments.

For example, if you have a function:

```Python
@lru_cache
def say_hi(name: str, salutation: str = "Ms."):
    return f"Hello {salutation} {name}"
```

your program could execute like this:

```mermaid
sequenceDiagram

participant code as Code
participant function as say_hi()
participant execute as Execute function

    rect rgba(0, 255, 0, .1)
        code ->> function: say_hi(name="Camila")
        function ->> execute: execute function code
        execute ->> code: return the result
    end

    rect rgba(0, 255, 255, .1)
        code ->> function: say_hi(name="Camila")
        function ->> code: return stored result
    end

    rect rgba(0, 255, 0, .1)
        code ->> function: say_hi(name="Rick")
        function ->> execute: execute function code
        execute ->> code: return the result
    end

    rect rgba(0, 255, 0, .1)
        code ->> function: say_hi(name="Rick", salutation="Mr.")
        function ->> execute: execute function code
        execute ->> code: return the result
    end

    rect rgba(0, 255, 255, .1)
        code ->> function: say_hi(name="Rick")
        function ->> code: return stored result
    end

    rect rgba(0, 255, 255, .1)
        code ->> function: say_hi(name="Camila")
        function ->> code: return stored result
    end
```

In the case of our dependency `get_settings()`, the function doesn't even take any arguments, so it always returns the same value.

That way, it behaves almost as if it was just a global variable. But as it uses a dependency function, then we can override it easily for testing.

`@lru_cache` is part of `functools` which is part of Python's standard library, you can read more about it in the [Python docs for `@lru_cache`](https://docs.python.org/3/library/functools.html#functools.lru_cache).


docs/en/docs/advanced/settings.md::Recap { #recap }::L296

# Doc: docs/en/docs/advanced/settings.md | Page: Settings and Environment Variables { #settings-and-environment-variables } | Section: Recap { #recap }
## Recap { #recap }

You can use Pydantic Settings to handle the settings or configurations for your application, with all the power of Pydantic models.

* By using a dependency you can simplify testing.
* You can use `.env` files with it.
* Using `@lru_cache` lets you avoid reading the dotenv file again and again for each request, while allowing you to override it during testing.


docs/en/docs/advanced/stream-data.md::Stream Data { #stream-data }::L1

# Doc: docs/en/docs/advanced/stream-data.md | Page: Stream Data { #stream-data } | Section: Stream Data { #stream-data }
# Stream Data { #stream-data }

If you want to stream data that can be structured as JSON, you should [Stream JSON Lines](../tutorial/stream-json-lines.md).

But if you want to **stream pure binary data** or strings, here's how you can do it.

/// note

Added in FastAPI 0.134.0.

///


docs/en/docs/advanced/stream-data.md::Use Cases { #use-cases }::L13

# Doc: docs/en/docs/advanced/stream-data.md | Page: Stream Data { #stream-data } | Section: Use Cases { #use-cases }
## Use Cases { #use-cases }

You could use this if you want to stream pure strings, for example directly from the output of an **AI LLM** service.

You could also use it to stream **large binary files**, where you stream each chunk of data as you read it, without having to read it all into memory at once.

You could also stream **video** or **audio** this way, it could even be generated as you process and send it.


docs/en/docs/advanced/stream-data.md::A `StreamingResponse` with `yield` { #a-streamingresponse-with-yield }::L21

# Doc: docs/en/docs/advanced/stream-data.md | Page: Stream Data { #stream-data } | Section: A `StreamingResponse` with `yield` { #a-streamingresponse-with-yield }
## A `StreamingResponse` with `yield` { #a-streamingresponse-with-yield }

If you declare a `response_class=StreamingResponse` in your *path operation function*, you can use `yield` to send each chunk of data in turn.

{* ../../docs_src/stream_data/tutorial001_py310.py ln[1:23] hl[20,23] *}

FastAPI will give each chunk of data to the `StreamingResponse` as is, it won't try to convert it to JSON or anything similar.

### Non-async *path operation functions* { #non-async-path-operation-functions }

You can also use regular `def` functions (without `async`), and use `yield` the same way.

{* ../../docs_src/stream_data/tutorial001_py310.py ln[26:29] hl[27] *}

### No Annotation { #no-annotation }

You don't really need to declare the return type annotation for streaming binary data.

As FastAPI will not try to convert the data to JSON with Pydantic or serialize it in any way, in this case, the type annotation is only for your editor and tools to use, it won't be used by FastAPI.

{* ../../docs_src/stream_data/tutorial001_py310.py ln[32:35] hl[33] *}

This also means that with `StreamingResponse` you have the **freedom** and **responsibility** to produce and encode the data bytes exactly as you need them to be sent, independent of the type annotations. 🤓

### Stream Bytes { #stream-bytes }

One of the main use cases would be to stream `bytes` instead of strings, you can of course do it.

{* ../../docs_src/stream_data/tutorial001_py310.py ln[44:47] hl[47] *}


docs/en/docs/advanced/stream-data.md::A Custom `PNGStreamingResponse` { #a-custom-pngstreamingresponse }::L51

# Doc: docs/en/docs/advanced/stream-data.md | Page: Stream Data { #stream-data } | Section: A Custom `PNGStreamingResponse` { #a-custom-pngstreamingresponse }
## A Custom `PNGStreamingResponse` { #a-custom-pngstreamingresponse }

In the examples above, the data bytes were streamed, but the response didn't have a `Content-Type` header, so the client didn't know what type of data it was receiving.

You can create a custom sub-class of `StreamingResponse` that sets the `Content-Type` header to the type of data you're streaming.

For example, you can create a `PNGStreamingResponse` that sets the `Content-Type` header to `image/png` using the `media_type` attribute:

{* ../../docs_src/stream_data/tutorial002_py310.py ln[6,19:20] hl[20] *}

Then you can use this new class in `response_class=PNGStreamingResponse` in your *path operation function*:

{* ../../docs_src/stream_data/tutorial002_py310.py ln[23:27] hl[23] *}

### Simulate a File { #simulate-a-file }

In this example, we are simulating a file with `io.BytesIO`, which is a file-like object that lives only in memory, but lets us use the same interface.

For example, we can iterate over it to consume its contents, as we could with a file.

{* ../../docs_src/stream_data/tutorial002_py310.py ln[1:27] hl[3,12:13,25] *}

/// note | Technical Details

The other two variables, `image_base64` and `binary_image`, are an image encoded in Base64, and then converted to bytes, to then pass it to `io.BytesIO`.

Only so that it can live in the same file for this example and you can copy it and run it as is. 🥚

///

By using a `with` block, we make sure that the file-like object is closed after the generator function (the function with `yield`) is done. So, after it finishes sending the response.

It wouldn't be that important in this specific example because it's a fake in-memory file (with `io.BytesIO`), but with a real file, it would be important to make sure the file is closed after the work with it is done.

### Files and Async { #files-and-async }

In most cases, file-like objects are not compatible with async and await by default.

For example, they don't have an `await file.read()`, or `async for chunk in file`.

And in many cases, reading them would be a blocking operation (that could block the event loop), because they are read from disk or from the network.

/// note

The example above is actually an exception, because the `io.BytesIO` object is already in memory, so reading it won't block anything.

But in many cases reading a file or a file-like object would block.

///

To avoid blocking the event loop, you can simply declare the *path operation function* with regular `def` instead of `async def`, that way FastAPI will run it on a threadpool worker, to avoid blocking the main loop.

{* ../../docs_src/stream_data/tutorial002_py310.py ln[30:34] hl[31] *}

/// tip

If you need to call blocking code from inside of an async function, or an async function from inside of a blocking function, you could use [Asyncer](https://asyncer.tiangolo.com), a sibling library to FastAPI.

///

### `yield from` { #yield-from }

When you are iterating over something, like a file-like object, and then you are doing `yield` for each item, you could also use `yield from` to yield each item directly and skip the `for` loop.

This is not particular to FastAPI, it's just Python, but it's a nice trick to know. 😎

{* ../../docs_src/stream_data/tutorial002_py310.py ln[37:40] hl[40] *}


docs/en/docs/advanced/strict-content-type.md::Strict Content-Type Checking { #strict-content-type-checking }::L1

# Doc: docs/en/docs/advanced/strict-content-type.md | Page: Strict Content-Type Checking { #strict-content-type-checking } | Section: Strict Content-Type Checking { #strict-content-type-checking }
# Strict Content-Type Checking { #strict-content-type-checking }

By default, **FastAPI** uses strict `Content-Type` header checking for JSON request bodies, this means that JSON requests **must** include a valid `Content-Type` header (e.g. `application/json`) in order for the body to be parsed as JSON.


docs/en/docs/advanced/strict-content-type.md::CSRF Risk { #csrf-risk }::L5

# Doc: docs/en/docs/advanced/strict-content-type.md | Page: Strict Content-Type Checking { #strict-content-type-checking } | Section: CSRF Risk { #csrf-risk }
## CSRF Risk { #csrf-risk }

This default behavior provides protection against a class of **Cross-Site Request Forgery (CSRF)** attacks in a very specific scenario.

These attacks exploit the fact that browsers allow scripts to send requests without doing any CORS preflight check when they:

* don't have a `Content-Type` header (e.g. using `fetch()` with a `Blob` body)
* and don't send any authentication credentials.

This type of attack is mainly relevant when:

* the application is running locally (e.g. on `localhost`) or in an internal network
* and the application doesn't have any authentication, it expects that any request from the same network can be trusted.


docs/en/docs/advanced/strict-content-type.md::Example Attack { #example-attack }::L19

# Doc: docs/en/docs/advanced/strict-content-type.md | Page: Strict Content-Type Checking { #strict-content-type-checking } | Section: Example Attack { #example-attack }
## Example Attack { #example-attack }

Imagine you build a way to run a local AI agent.

It provides an API at

```
http://localhost:8000/v1/agents/multivac
```

There's also a frontend at

```
http://localhost:8000
```

/// tip

Note that both have the same host.

///

Then using the frontend you can make the AI agent do things on your behalf.

As it's running **locally**, and not in the open internet, you decide to **not have any authentication** set up, just trusting the access to the local network.

Then one of your users could install it and run it locally.

Then they could open a malicious website, e.g. something like

```
https://evilhackers.example.com
```

And that malicious website sends requests using `fetch()` with a `Blob` body to the local API at

```
http://localhost:8000/v1/agents/multivac
```

Even though the host of the malicious website and the local app is different, the browser won't trigger a CORS preflight request because:

* It's running without any authentication, it doesn't have to send any credentials.
* The browser thinks it's not sending JSON (because of the missing `Content-Type` header).

Then the malicious website could make the local AI agent send angry messages to the user's ex-boss... or worse. 😅


docs/en/docs/advanced/strict-content-type.md::Open Internet { #open-internet }::L66

# Doc: docs/en/docs/advanced/strict-content-type.md | Page: Strict Content-Type Checking { #strict-content-type-checking } | Section: Open Internet { #open-internet }
## Open Internet { #open-internet }

If your app is in the open internet, you wouldn't "trust the network" and let anyone send privileged requests without authentication.

Attackers could simply run a script to send requests to your API, no need for browser interaction, so you are probably already securing any privileged endpoints.

In that case **this attack / risk doesn't apply to you**.

This risk and attack is mainly relevant when the app runs on the **local network** and that is the **only assumed protection**.


docs/en/docs/advanced/strict-content-type.md::Allowing Requests Without Content-Type { #allowing-requests-without-content-type }::L76

# Doc: docs/en/docs/advanced/strict-content-type.md | Page: Strict Content-Type Checking { #strict-content-type-checking } | Section: Allowing Requests Without Content-Type { #allowing-requests-without-content-type }
## Allowing Requests Without Content-Type { #allowing-requests-without-content-type }

If you need to support clients that don't send a `Content-Type` header, you can disable strict checking by setting `strict_content_type=False`:

{* ../../docs_src/strict_content_type/tutorial001_py310.py hl[4] *}

With this setting, requests without a `Content-Type` header will have their body parsed as JSON, which is the same behavior as older versions of FastAPI.

/// note

This behavior and configuration was added in FastAPI 0.132.0.

///


docs/en/docs/advanced/sub-applications.md::Sub Applications - Mounts { #sub-applications-mounts }::L1

# Doc: docs/en/docs/advanced/sub-applications.md | Page: Sub Applications - Mounts { #sub-applications-mounts } | Section: Sub Applications - Mounts { #sub-applications-mounts }
# Sub Applications - Mounts { #sub-applications-mounts }

If you need to have two independent FastAPI applications, with their own independent OpenAPI and their own docs UIs, you can have a main app and "mount" one (or more) sub-application(s).


docs/en/docs/advanced/sub-applications.md::Mounting a **FastAPI** application { #mounting-a-fastapi-application }::L5

# Doc: docs/en/docs/advanced/sub-applications.md | Page: Sub Applications - Mounts { #sub-applications-mounts } | Section: Mounting a **FastAPI** application { #mounting-a-fastapi-application }
## Mounting a **FastAPI** application { #mounting-a-fastapi-application }

"Mounting" means adding a completely "independent" application in a specific path, that then takes care of handling everything under that path, with the _path operations_ declared in that sub-application.

### Top-level application { #top-level-application }

First, create the main, top-level, **FastAPI** application, and its *path operations*:

{* ../../docs_src/sub_applications/tutorial001_py310.py hl[3, 6:8] *}

### Sub-application { #sub-application }

Then, create your sub-application, and its *path operations*.

This sub-application is just another standard FastAPI application, but this is the one that will be "mounted":

{* ../../docs_src/sub_applications/tutorial001_py310.py hl[11, 14:16] *}

### Mount the sub-application { #mount-the-sub-application }

In your top-level application, `app`, mount the sub-application, `subapi`.

In this case, it will be mounted at the path `/subapi`:

{* ../../docs_src/sub_applications/tutorial001_py310.py hl[11, 19] *}

### Check the automatic API docs { #check-the-automatic-api-docs }

Now, run the `fastapi` command:

```console
$ fastapi dev

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```

And open the docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).

You will see the automatic API docs for the main app, including only its own _path operations_:

And then, open the docs for the sub-application, at [http://127.0.0.1:8000/subapi/docs](http://127.0.0.1:8000/subapi/docs).

You will see the automatic API docs for the sub-application, including only its own _path operations_, all under the correct sub-path prefix `/subapi`:

If you try interacting with any of the two user interfaces, they will work correctly, because the browser will be able to talk to each specific app or sub-app.

### Technical Details: `root_path` { #technical-details-root-path }

When you mount a sub-application as described above, FastAPI will take care of communicating the mount path for the sub-application using a mechanism from the ASGI specification called a `root_path`.

That way, the sub-application will know to use that path prefix for the docs UI.

And the sub-application could also have its own mounted sub-applications and everything would work correctly, because FastAPI handles all these `root_path`s automatically.

You will learn more about the `root_path` and how to use it explicitly in the section about [Behind a Proxy](behind-a-proxy.md).


docs/en/docs/advanced/templates.md::Templates { #templates }::L1

# Doc: docs/en/docs/advanced/templates.md | Page: Templates { #templates } | Section: Templates { #templates }
# Templates { #templates }

You can use any template engine you want with **FastAPI**.

A common choice is Jinja2, the same one used by Flask and other tools.

There are utilities to configure it easily that you can use directly in your **FastAPI** application (provided by Starlette).


docs/en/docs/advanced/templates.md::Install dependencies { #install-dependencies }::L9

# Doc: docs/en/docs/advanced/templates.md | Page: Templates { #templates } | Section: Install dependencies { #install-dependencies }
## Install dependencies { #install-dependencies }

Make sure you create a [virtual environment](../virtual-environments.md), activate it, and install `jinja2`:

<div class="termy">

```console
$ pip install jinja2

---> 100%
```

</div>


docs/en/docs/advanced/templates.md::Using `Jinja2Templates` { #using-jinja2templates }::L23

# Doc: docs/en/docs/advanced/templates.md | Page: Templates { #templates } | Section: Using `Jinja2Templates` { #using-jinja2templates }
## Using `Jinja2Templates` { #using-jinja2templates }

* Import `Jinja2Templates`.
* Create a `templates` object that you can reuse later.
* Declare a `Request` parameter in the *path operation* that will return a template.
* Use the `templates` you created to render and return a `TemplateResponse`, pass the name of the template, the request object, and a "context" dictionary with key-value pairs to be used inside of the Jinja2 template.

{* ../../docs_src/templates/tutorial001_py310.py hl[4,11,15:18] *}

/// note

Before FastAPI 0.108.0, Starlette 0.29.0, the `name` was the first parameter.

Also, before that, in previous versions, the `request` object was passed as part of the key-value pairs in the context for Jinja2.

///

/// tip

By declaring `response_class=HTMLResponse` the docs UI will be able to know that the response will be HTML.

///

/// note | Technical Details

You could also use `from starlette.templating import Jinja2Templates`.

**FastAPI** provides the same `starlette.templating` as `fastapi.templating` just as a convenience for you, the developer. But most of the available responses come directly from Starlette. The same with `Request` and `StaticFiles`.

///


docs/en/docs/advanced/templates.md::Writing templates { #writing-templates }::L54

# Doc: docs/en/docs/advanced/templates.md | Page: Templates { #templates } | Section: Writing templates { #writing-templates }
## Writing templates { #writing-templates }

Then you can write a template at `templates/item.html` with, for example:

```jinja hl_lines="7"
{!../../docs_src/templates/templates/item.html!}
```

### Template Context Values { #template-context-values }

In the HTML that contains:

{% raw %}

```jinja
Item ID: {{ id }}
```

{% endraw %}

...it will show the `id` taken from the "context" `dict` you passed:

```Python
{"id": id}
```

For example, with an ID of `42`, this would render:

```html
Item ID: 42
```

### Template `url_for` Arguments { #template-url-for-arguments }

You can also use `url_for()` inside of the template, it takes as arguments the same arguments that would be used by your *path operation function*.

So, the section with:

{% raw %}

```jinja
<a href="{{ url_for('read_item', id=id) }}">
```

{% endraw %}

...will generate a link to the same URL that would be handled by the *path operation function* `read_item(id=id)`.

For example, with an ID of `42`, this would render:

```html
<a href="/items/42">
```


docs/en/docs/advanced/templates.md::Templates and static files { #templates-and-static-files }::L108

# Doc: docs/en/docs/advanced/templates.md | Page: Templates { #templates } | Section: Templates and static files { #templates-and-static-files }
## Templates and static files { #templates-and-static-files }

You can also use `url_for()` inside of the template, and use it, for example, with the `StaticFiles` you mounted with the `name="static"`.

```jinja hl_lines="4"
{!../../docs_src/templates/templates/item.html!}
```

In this example, it would link to a CSS file at `static/styles.css` with:

```CSS hl_lines="4"
{!../../docs_src/templates/static/styles.css!}
```

And because you are using `StaticFiles`, that CSS file would be served automatically by your **FastAPI** application at the URL `/static/styles.css`.


docs/en/docs/advanced/templates.md::More details { #more-details }::L124

# Doc: docs/en/docs/advanced/templates.md | Page: Templates { #templates } | Section: More details { #more-details }
## More details { #more-details }

For more details, including how to test templates, check [Starlette's docs on templates](https://www.starlette.dev/templates/).


docs/en/docs/advanced/testing-dependencies.md::Testing Dependencies with Overrides { #testing-dependencies-with-overrides }::L1

# Doc: docs/en/docs/advanced/testing-dependencies.md | Page: Testing Dependencies with Overrides { #testing-dependencies-with-overrides } | Section: Testing Dependencies with Overrides { #testing-dependencies-with-overrides }
# Testing Dependencies with Overrides { #testing-dependencies-with-overrides }


docs/en/docs/advanced/testing-dependencies.md::Overriding dependencies during testing { #overriding-dependencies-during-testing }::L3

# Doc: docs/en/docs/advanced/testing-dependencies.md | Page: Testing Dependencies with Overrides { #testing-dependencies-with-overrides } | Section: Overriding dependencies during testing { #overriding-dependencies-during-testing }
## Overriding dependencies during testing { #overriding-dependencies-during-testing }

There are some scenarios where you might want to override a dependency during testing.

You don't want the original dependency to run (nor any of the sub-dependencies it might have).

Instead, you want to provide a different dependency that will be used only during tests (possibly only some specific tests), and will provide a value that can be used where the value of the original dependency was used.

### Use cases: external service { #use-cases-external-service }

An example could be that you have an external authentication provider that you need to call.

You send it a token and it returns an authenticated user.

This provider might be charging you per request, and calling it might take some extra time than if you had a fixed mock user for tests.

You probably want to test the external provider once, but not necessarily call it for every test that runs.

In this case, you can override the dependency that calls that provider, and use a custom dependency that returns a mock user, only for your tests.

### Use the `app.dependency_overrides` attribute { #use-the-app-dependency-overrides-attribute }

For these cases, your **FastAPI** application has an attribute `app.dependency_overrides`, it is a simple `dict`.

To override a dependency for testing, you put as a key the original dependency (a function), and as the value, your dependency override (another function).

And then **FastAPI** will call that override instead of the original dependency.

{* ../../docs_src/dependency_testing/tutorial001_an_py310.py hl[26:27,30] *}

/// tip

You can set a dependency override for a dependency used anywhere in your **FastAPI** application.

The original dependency could be used in a *path operation function*, a *path operation decorator* (when you don't use the return value), a `.include_router()` call, etc.

FastAPI will still be able to override it.

///

Then you can reset your overrides (remove them) by setting `app.dependency_overrides` to be an empty `dict`:

```Python
app.dependency_overrides = {}
```

/// tip

If you want to override a dependency only during some tests, you can set the override at the beginning of the test (inside the test function) and reset it at the end (at the end of the test function).

///


docs/en/docs/advanced/testing-events.md::Testing Events: lifespan and startup - shutdown { #testing-events-lifespan-and-startup-shutdown }::L1

# Doc: docs/en/docs/advanced/testing-events.md | Page: Testing Events: lifespan and startup - shutdown { #testing-events-lifespan-and-startup-shutdown } | Section: Testing Events: lifespan and startup - shutdown { #testing-events-lifespan-and-startup-shutdown }
# Testing Events: lifespan and startup - shutdown { #testing-events-lifespan-and-startup-shutdown }

When you need `lifespan` to run in your tests, you can use the `TestClient` with a `with` statement:

{* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *}

You can read more details about the ["Running lifespan in tests in the official Starlette documentation site."](https://www.starlette.dev/lifespan/#running-lifespan-in-tests)

For the deprecated `startup` and `shutdown` events, you can use the `TestClient` as follows:

{* ../../docs_src/app_testing/tutorial003_py310.py hl[9:12,20:24] *}


docs/en/docs/advanced/testing-websockets.md::Testing WebSockets { #testing-websockets }::L1

# Doc: docs/en/docs/advanced/testing-websockets.md | Page: Testing WebSockets { #testing-websockets } | Section: Testing WebSockets { #testing-websockets }
# Testing WebSockets { #testing-websockets }

You can use the same `TestClient` to test WebSockets.

For this, you use the `TestClient` in a `with` statement, connecting to the WebSocket:

{* ../../docs_src/app_testing/tutorial002_py310.py hl[27:31] *}

/// note

For more details, check Starlette's documentation for [testing WebSockets](https://www.starlette.dev/testclient/#testing-websocket-sessions).

///


docs/en/docs/advanced/using-request-directly.md::Using the Request Directly { #using-the-request-directly }::L1

# Doc: docs/en/docs/advanced/using-request-directly.md | Page: Using the Request Directly { #using-the-request-directly } | Section: Using the Request Directly { #using-the-request-directly }
# Using the Request Directly { #using-the-request-directly }

Up to now, you have been declaring the parts of the request that you need with their types.

Taking data from:

* The path as parameters.
* Headers.
* Cookies.
* etc.

And by doing so, **FastAPI** is validating that data, converting it and generating documentation for your API automatically.

But there are situations where you might need to access the `Request` object directly.


docs/en/docs/advanced/using-request-directly.md::Details about the `Request` object { #details-about-the-request-object }::L16

# Doc: docs/en/docs/advanced/using-request-directly.md | Page: Using the Request Directly { #using-the-request-directly } | Section: Details about the `Request` object { #details-about-the-request-object }
## Details about the `Request` object { #details-about-the-request-object }

As **FastAPI** is actually **Starlette** underneath, with a layer of several tools on top, you can use Starlette's [`Request`](https://www.starlette.dev/requests/) object directly when you need to.

It would also mean that if you get data from the `Request` object directly (for example, read the body) it won't be validated, converted or documented (with OpenAPI, for the automatic API user interface) by FastAPI.

Although any other parameter declared normally (for example, the body with a Pydantic model) would still be validated, converted, annotated, etc.

But there are specific cases where it's useful to get the `Request` object.


docs/en/docs/advanced/using-request-directly.md::Use the `Request` object directly { #use-the-request-object-directly }::L26

# Doc: docs/en/docs/advanced/using-request-directly.md | Page: Using the Request Directly { #using-the-request-directly } | Section: Use the `Request` object directly { #use-the-request-object-directly }
## Use the `Request` object directly { #use-the-request-object-directly }

Let's imagine you want to get the client's IP address/host inside of your *path operation function*.

For that you need to access the request directly.

{* ../../docs_src/using_request_directly/tutorial001_py310.py hl[1,7:8] *}

By declaring a *path operation function* parameter with the type being the `Request` **FastAPI** will know to pass the `Request` in that parameter.

/// tip

Note that in this case, we are declaring a path parameter beside the request parameter.

So, the path parameter will be extracted, validated, converted to the specified type and annotated with OpenAPI.

The same way, you can declare any other parameter as normally, and additionally, get the `Request` too.

///


docs/en/docs/advanced/using-request-directly.md::`Request` documentation { #request-documentation }::L46

# Doc: docs/en/docs/advanced/using-request-directly.md | Page: Using the Request Directly { #using-the-request-directly } | Section: `Request` documentation { #request-documentation }
## `Request` documentation { #request-documentation }

You can read more details about the [`Request` object in the official Starlette documentation site](https://www.starlette.dev/requests/).

/// note | Technical Details

You could also use `from starlette.requests import Request`.

**FastAPI** provides it directly just as a convenience for you, the developer. But it comes directly from Starlette.

///


docs/en/docs/advanced/websockets.md::WebSockets { #websockets }::L1

# Doc: docs/en/docs/advanced/websockets.md | Page: WebSockets { #websockets } | Section: WebSockets { #websockets }
# WebSockets { #websockets }

You can use [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) with **FastAPI**.


docs/en/docs/advanced/websockets.md::Install `websockets` { #install-websockets }::L5

# Doc: docs/en/docs/advanced/websockets.md | Page: WebSockets { #websockets } | Section: Install `websockets` { #install-websockets }
## Install `websockets` { #install-websockets }

Make sure you create a [virtual environment](../virtual-environments.md), activate it, and install `websockets` (a Python library that makes it easy to use the "WebSocket" protocol):

<div class="termy">

```console
$ pip install websockets

---> 100%
```

</div>


docs/en/docs/advanced/websockets.md::WebSockets client { #websockets-client }::L19

# Doc: docs/en/docs/advanced/websockets.md | Page: WebSockets { #websockets } | Section: WebSockets client { #websockets-client }
## WebSockets client { #websockets-client }

### In production { #in-production }

In your production system, you probably have a frontend created with a modern framework like React, Vue.js or Angular.

And to communicate using WebSockets with your backend you would probably use your frontend's utilities.

Or you might have a native mobile application that communicates with your WebSocket backend directly, in native code.

Or you might have any other way to communicate with the WebSocket endpoint.

---

But for this example, we'll use a very simple HTML document with some JavaScript, all inside a long string.

This, of course, is not optimal and you wouldn't use it for production.

In production you would have one of the options above.

But it's the simplest way to focus on the server-side of WebSockets and have a working example:

{* ../../docs_src/websockets_/tutorial001_py310.py hl[2,6:38,41:43] *}


docs/en/docs/advanced/websockets.md::Create a `websocket` { #create-a-websocket }::L43

# Doc: docs/en/docs/advanced/websockets.md | Page: WebSockets { #websockets } | Section: Create a `websocket` { #create-a-websocket }
## Create a `websocket` { #create-a-websocket }

In your **FastAPI** application, create a `websocket`:

{* ../../docs_src/websockets_/tutorial001_py310.py hl[1,46:47] *}

/// note | Technical Details

You could also use `from starlette.websockets import WebSocket`.

**FastAPI** provides the same `WebSocket` directly just as a convenience for you, the developer. But it comes directly from Starlette.

///


docs/en/docs/advanced/websockets.md::Await for messages and send messages { #await-for-messages-and-send-messages }::L57

# Doc: docs/en/docs/advanced/websockets.md | Page: WebSockets { #websockets } | Section: Await for messages and send messages { #await-for-messages-and-send-messages }
## Await for messages and send messages { #await-for-messages-and-send-messages }

In your WebSocket route you can `await` for messages and send messages.

{* ../../docs_src/websockets_/tutorial001_py310.py hl[48:52] *}

You can receive and send binary, text, and JSON data.


docs/en/docs/advanced/websockets.md::Try it { #try-it }::L65

# Doc: docs/en/docs/advanced/websockets.md | Page: WebSockets { #websockets } | Section: Try it { #try-it }
## Try it { #try-it }

Put your code in a file `main.py` and then run your application:

```console
$ fastapi dev

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```

Open your browser at [http://127.0.0.1:8000](http://127.0.0.1:8000).

You will see a simple page like:

You can type messages in the input box, and send them:

And your **FastAPI** application with WebSockets will respond back:

You can send (and receive) many messages:

And all of them will use the same WebSocket connection.


docs/en/docs/advanced/websockets.md::Using `Depends` and others { #using-depends-and-others }::L99

# Doc: docs/en/docs/advanced/websockets.md | Page: WebSockets { #websockets } | Section: Using `Depends` and others { #using-depends-and-others }
## Using `Depends` and others { #using-depends-and-others }

In WebSocket endpoints you can import from `fastapi` and use:

* `Depends`
* `Security`
* `Cookie`
* `Header`
* `Path`
* `Query`

They work the same way as for other FastAPI endpoints/*path operations*:

{* ../../docs_src/websockets_/tutorial002_an_py310.py hl[68:69,82] *}

/// note

As this is a WebSocket it doesn't really make sense to raise an `HTTPException`, instead we raise a `WebSocketException`.

You can use a closing code from the [valid codes defined in the specification](https://tools.ietf.org/html/rfc6455#section-7.4.1).

///

### Try the WebSockets with dependencies { #try-the-websockets-with-dependencies }

Run your application:

```console
$ fastapi dev

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```

Open your browser at [http://127.0.0.1:8000](http://127.0.0.1:8000).

There you can set:

* The "Item ID", used in the path.
* The "Token" used as a query parameter.

/// tip

Notice that the query `token` will be handled by a dependency.

///

With that you can connect the WebSocket and then send and receive messages:


docs/en/docs/advanced/websockets.md::Handling disconnections and multiple clients { #handling-disconnections-and-multiple-clients }::L153

# Doc: docs/en/docs/advanced/websockets.md | Page: WebSockets { #websockets } | Section: Handling disconnections and multiple clients { #handling-disconnections-and-multiple-clients }
## Handling disconnections and multiple clients { #handling-disconnections-and-multiple-clients }

When a WebSocket connection is closed, the `await websocket.receive_text()` will raise a `WebSocketDisconnect` exception, which you can then catch and handle like in this example.

{* ../../docs_src/websockets_/tutorial003_py310.py hl[79:81] *}

To try it out:

* Open the app with several browser tabs.
* Write messages from them.
* Then close one of the tabs.

That will raise the `WebSocketDisconnect` exception, and all the other clients will receive a message like:

```
Client #1596980209979 left the chat
```

/// tip

The app above is a minimal and simple example to demonstrate how to handle and broadcast messages to several WebSocket connections.

But keep in mind that, as everything is handled in memory, in a single list, it will only work while the process is running, and will only work with a single process.

If you need something easy to integrate with FastAPI but that is more robust, supported by Redis, PostgreSQL or others, check [encode/broadcaster](https://github.com/encode/broadcaster).

///


docs/en/docs/advanced/websockets.md::More info { #more-info }::L181

# Doc: docs/en/docs/advanced/websockets.md | Page: WebSockets { #websockets } | Section: More info { #more-info }
## More info { #more-info }

To learn more about the options, check Starlette's documentation for:

* [The `WebSocket` class](https://www.starlette.dev/websockets/).
* [Class-based WebSocket handling](https://www.starlette.dev/endpoints/#websocketendpoint).


docs/en/docs/advanced/wsgi.md::Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others }::L1

# Doc: docs/en/docs/advanced/wsgi.md | Page: Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others } | Section: Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others }
# Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others }

You can mount WSGI applications as you saw with [Sub Applications - Mounts](sub-applications.md), [Behind a Proxy](behind-a-proxy.md).

For that, you can use the `WSGIMiddleware` and use it to wrap your WSGI application, for example, Flask, Django, etc.


docs/en/docs/advanced/wsgi.md::Using `WSGIMiddleware` { #using-wsgimiddleware }::L7

# Doc: docs/en/docs/advanced/wsgi.md | Page: Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others } | Section: Using `WSGIMiddleware` { #using-wsgimiddleware }
## Using `WSGIMiddleware` { #using-wsgimiddleware }

/// note

This requires installing `a2wsgi` for example with `pip install a2wsgi`.

///

You need to import `WSGIMiddleware` from `a2wsgi`.

Then wrap the WSGI (e.g. Flask) app with the middleware.

And then mount that under a path.

{* ../../docs_src/wsgi/tutorial001_py310.py hl[1,3,23] *}

/// note

Previously, it was recommended to use `WSGIMiddleware` from `fastapi.middleware.wsgi`, but it is now deprecated.

It's advised to use the `a2wsgi` package instead. The usage remains the same.

Just ensure that you have the `a2wsgi` package installed and import `WSGIMiddleware` correctly from `a2wsgi`.

///


docs/en/docs/advanced/wsgi.md::Check it { #check-it }::L33

# Doc: docs/en/docs/advanced/wsgi.md | Page: Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others } | Section: Check it { #check-it }
## Check it { #check-it }

Now, every request under the path `/v1/` will be handled by the Flask application.

And the rest will be handled by **FastAPI**.

If you run it and go to [http://localhost:8000/v1/](http://localhost:8000/v1/) you will see the response from Flask:

```txt
Hello, World from Flask!
```

And if you go to [http://localhost:8000/v2](http://localhost:8000/v2) you will see the response from FastAPI:

```JSON
{
    "message": "Hello World"
}
```


docs/en/docs/alternatives.md::Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons }::L1

# Doc: docs/en/docs/alternatives.md | Page: Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons } | Section: Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons }
# Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons }

What inspired **FastAPI**, how it compares to alternatives and what it learned from them.


docs/en/docs/alternatives.md::Intro { #intro }::L5

# Doc: docs/en/docs/alternatives.md | Page: Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons } | Section: Intro { #intro }
## Intro { #intro }

**FastAPI** wouldn't exist if not for the previous work of others.

There have been many tools created before that have helped inspire its creation.

I have been avoiding the creation of a new framework for several years. First I tried to solve all the features covered by **FastAPI** using many different frameworks, plug-ins, and tools.

But at some point, there was no other option than creating something that provided all these features, taking the best ideas from previous tools, and combining them in the best way possible, using language features that weren't even available before (Python 3.6+ type hints).


docs/en/docs/alternatives.md::Previous tools { #previous-tools }::L15

# Doc: docs/en/docs/alternatives.md | Page: Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons } | Section: Previous tools { #previous-tools }
## Previous tools { #previous-tools }

### [Django](https://www.djangoproject.com/) { #django }

It's the most popular Python framework and is widely trusted. It is used to build systems like Instagram.

It's relatively tightly coupled with relational databases (like MySQL or PostgreSQL), so, having a NoSQL database (like Couchbase, MongoDB, Cassandra, etc) as the main store engine is not very easy.

It was created to generate the HTML in the backend, not to create APIs used by a modern frontend (like React, Vue.js and Angular) or by other systems (like <abbr title="Internet of Things">IoT</abbr> devices) communicating with it.

### [Django REST Framework](https://www.django-rest-framework.org/) { #django-rest-framework }

Django REST Framework was created to be a flexible toolkit for building Web APIs using Django underneath, to improve its API capabilities.

It is used by many companies including Mozilla, Red Hat and Eventbrite.

It was one of the first examples of **automatic API documentation**, and this was specifically one of the first ideas that inspired "the search for" **FastAPI**.

/// note

Django REST Framework was created by Tom Christie. The same creator of Starlette and Uvicorn, on which **FastAPI** is based.

///

/// tip | Inspired **FastAPI** to

Have an automatic API documentation web user interface.

///

### [Flask](https://flask.palletsprojects.com) { #flask }

Flask is a "microframework", it doesn't include database integrations nor many of the things that come by default in Django.

This simplicity and flexibility allow doing things like using NoSQL databases as the main data storage system.

As it is very simple, it's relatively intuitive to learn, although the documentation gets somewhat technical at some points.

It is also commonly used for other applications that don't necessarily need a database, user management, or any of the many features that come pre-built in Django. Although many of these features can be added with plug-ins.

This decoupling of parts, and being a "microframework" that could be extended to cover exactly what is needed was a key feature that I wanted to keep.

Given the simplicity of Flask, it seemed like a good match for building APIs. The next thing to find was a "Django REST Framework" for Flask.

/// tip | Inspired **FastAPI** to

Be a micro-framework. Making it easy to mix and match the tools and parts needed.

Have a simple and easy to use routing system.

///

### [Requests](https://requests.readthedocs.io) { #requests }

**FastAPI** is not actually an alternative to **Requests**. Their scope is very different.

It would actually be common to use Requests *inside* of a FastAPI application.

But still, FastAPI got quite some inspiration from Requests.

**Requests** is a library to *interact* with APIs (as a client), while **FastAPI** is a library to *build* APIs (as a server).

They are, more or less, at opposite ends, complementing each other.

Requests has a very simple and intuitive design, it's very easy to use, with sensible defaults. But at the same time, it's very powerful and customizable.

That's why, as said in the official website:

> Requests is one of the most downloaded Python packages of all time

The way you use it is very simple. For example, to do a `GET` request, you would write:

```Python
response = requests.get("http://example.com/some/url")
```

The FastAPI counterpart API *path operation* could look like:

```Python hl_lines="1"
@app.get("/some/url")
def read_url():
    return {"message": "Hello World"}
```

See the similarities in `requests.get(...)` and `@app.get(...)`.

/// tip | Inspired **FastAPI** to

* Have a simple and intuitive API.
* Use HTTP method names (operations) directly, in a straightforward and intuitive way.
* Have sensible defaults, but powerful customizations.

///

### [Swagger](https://swagger.io/) / [OpenAPI](https://github.com/OAI/OpenAPI-Specification/) { #swagger-openapi }

The main feature I wanted from Django REST Framework was the automatic API documentation.

Then I found that there was a standard to document APIs, using JSON (or YAML, an extension of JSON) called Swagger.

And there was a web user interface for Swagger APIs already created. So, being able to generate Swagger documentation for an API would allow using this web user interface automatically.

At some point, Swagger was given to the Linux Foundation, to be renamed OpenAPI.

That's why when talking about version 2.0 it's common to say "Swagger", and for version 3+ "OpenAPI".

/// tip | Inspired **FastAPI** to

Adopt and use an open standard for API specifications, instead of a custom schema.

And integrate standards-based user interface tools:

* [Swagger UI](https://github.com/swagger-api/swagger-ui)
* [ReDoc](https://github.com/Rebilly/ReDoc)

These two were chosen for being fairly popular and stable, but doing a quick search, you could find dozens of alternative user interfaces for OpenAPI (that you can use with **FastAPI**).

///

### Flask REST frameworks { #flask-rest-frameworks }

There are several Flask REST frameworks, but after investing the time and work into investigating them, I found that many are discontinued or abandoned, with several standing issues that made them unfit.

### [Marshmallow](https://marshmallow.readthedocs.io/en/stable/) { #marshmallow }

One of the main features needed by API systems is data "<dfn title="also called marshalling, conversion">serialization</dfn>" which is taking data from the code (Python) and converting it into something that can be sent through the network. For example, converting an object containing data from a database into a JSON object. Converting `datetime` objects into strings, etc.

Another big feature needed by APIs is data validation, making sure that the data is valid, given certain parameters. For example, that some field is an `int`, and not some random string. This is especially useful for incoming data.

Without a data validation system, you would have to do all the checks by hand, in code.

These features are what Marshmallow was built to provide. It is a great library, and I have used it a lot before.

But it was created before there existed Python type hints. So, to define every <dfn title="the definition of how data should be formed">schema</dfn> you need to use specific utils and classes provided by Marshmallow.

/// tip | Inspired **FastAPI** to

Use code to define "schemas" that provide data types and validation, automatically.

///

### [Webargs](https://webargs.readthedocs.io/en/latest/) { #webargs }

Another big feature required by APIs is <dfn title="reading and converting to Python data">parsing</dfn> data from incoming requests.

Webargs is a tool that was made to provide that on top of several frameworks, including Flask.

It uses Marshmallow underneath to do the data validation. And it was created by the same developers.

It's a great tool and I have used it a lot too, before having **FastAPI**.

/// note

Webargs was created by the same Marshmallow developers.

///

/// tip | Inspired **FastAPI** to

Have automatic validation of incoming request data.

///

### [APISpec](https://apispec.readthedocs.io/en/stable/) { #apispec }

Marshmallow and Webargs provide validation, parsing and serialization as plug-ins.

But documentation is still missing. Then APISpec was created.

It is a plug-in for many frameworks (and there's a plug-in for Starlette too).

The way it works is that you write the definition of the schema using YAML format inside the docstring of each function handling a route.

And it generates OpenAPI schemas.

That's how it works in Flask, Starlette, Responder, etc.

But then, we have again the problem of having a micro-syntax, inside of a Python string (a big YAML).

The editor can't help much with that. And if we modify parameters or Marshmallow schemas and forget to also modify that YAML docstring, the generated schema would be obsolete.

/// note

APISpec was created by the same Marshmallow developers.

///

/// tip | Inspired **FastAPI** to

Support the open standard for APIs, OpenAPI.

///

### [Flask-apispec](https://flask-apispec.readthedocs.io/en/latest/) { #flask-apispec }

It's a Flask plug-in, that ties together Webargs, Marshmallow and APISpec.

It uses the information from Webargs and Marshmallow to automatically generate OpenAPI schemas, using APISpec.

It's a great tool, very underrated. It should be way more popular than many Flask plug-ins out there. It might be due to its documentation being too concise and abstract.

This solved having to write YAML (another syntax) inside of Python docstrings.

This combination of Flask, Flask-apispec with Marshmallow and Webargs was my favorite backend stack until building **FastAPI**.

Using it led to the creation of several Flask full-stack generators. These are the main stacks I (and several external teams) have been using up to now:

* [https://github.com/tiangolo/full-stack](https://github.com/tiangolo/full-stack)
* [https://github.com/tiangolo/full-stack-flask-couchbase](https://github.com/tiangolo/full-stack-flask-couchbase)
* [https://github.com/tiangolo/full-stack-flask-couchdb](https://github.com/tiangolo/full-stack-flask-couchdb)

And these same full-stack generators were the base of the [**FastAPI** Project Generators](project-generation.md).

/// note

Flask-apispec was created by the same Marshmallow developers.

///

/// tip | Inspired **FastAPI** to

Generate the OpenAPI schema automatically, from the same code that defines serialization and validation.

///

### [NestJS](https://nestjs.com/) (and [Angular](https://angular.io/)) { #nestjs-and-angular }

This isn't even Python, NestJS is a JavaScript (TypeScript) NodeJS framework inspired by Angular.

It achieves something somewhat similar to what can be done with Flask-apispec.

It has an integrated dependency injection system, inspired by Angular 2. It requires pre-registering the "injectables" (like all the other dependency injection systems I know), so, it adds to the verbosity and code repetition.

As the parameters are described with TypeScript types (similar to Python type hints), editor support is quite good.

But as TypeScript data is not preserved after compilation to JavaScript, it cannot rely on the types to define validation, serialization and documentation at the same time. Due to this and some design decisions, to get validation, serialization and automatic schema generation, it's needed to add decorators in many places. So, it becomes quite verbose.

It can't handle nested models very well. So, if the JSON body in the request is a JSON object that has inner fields that in turn are nested JSON objects, it cannot be properly documented and validated.

/// tip | Inspired **FastAPI** to

Use Python types to have great editor support.

Have a powerful dependency injection system. Find a way to minimize code repetition.

///

### [Sanic](https://sanic.readthedocs.io/en/latest/) { #sanic }

It was one of the first extremely fast Python frameworks based on `asyncio`. It was made to be very similar to Flask.

/// note | Technical Details

It used [`uvloop`](https://github.com/MagicStack/uvloop) instead of the default Python `asyncio` loop. That's what made it so fast.

It clearly inspired Uvicorn and Starlette, that are currently faster than Sanic in open benchmarks.

///

/// tip | Inspired **FastAPI** to

Find a way to have a crazy performance.

That's why **FastAPI** is based on Starlette, as it is the fastest framework available (tested by third-party benchmarks).

///

### [Falcon](https://falconframework.org/) { #falcon }

Falcon is another high performance Python framework, it is designed to be minimal, and work as the foundation of other frameworks like Hug.

It is designed to have functions that receive two parameters, one "request" and one "response". Then you "read" parts from the request, and "write" parts to the response. Because of this design, it is not possible to declare request parameters and bodies with standard Python type hints as function parameters.

So, data validation, serialization, and documentation, have to be done in code, not automatically. Or they have to be implemented as a framework on top of Falcon, like Hug. This same distinction happens in other frameworks that are inspired by Falcon's design, of having one request object and one response object as parameters.

/// tip | Inspired **FastAPI** to

Find ways to get great performance.

Along with Hug (as Hug is based on Falcon) inspired **FastAPI** to declare a `response` parameter in functions.

Although in FastAPI it's optional, and is used mainly to set headers, cookies, and alternative status codes.

///

### [Molten](https://moltenframework.com/) { #molten }

I discovered Molten in the first stages of building **FastAPI**. And it has quite similar ideas:

* Based on Python type hints.
* Validation and documentation from these types.
* Dependency Injection system.

It doesn't use a data validation, serialization and documentation third-party library like Pydantic, it has its own. So, these data type definitions would not be reusable as easily.

It requires a little bit more verbose configurations. And as it is based on WSGI (instead of ASGI), it is not designed to take advantage of the high performance provided by tools like Uvicorn, Starlette and Sanic.

The dependency injection system requires pre-registration of the dependencies and the dependencies are solved based on the declared types. So, it's not possible to declare more than one "component" that provides a certain type.

Routes are declared in a single place, using functions declared in other places (instead of using decorators that can be placed right on top of the function that handles the endpoint). This is closer to how Django does it than to how Flask (and Starlette) does it. It separates in the code things that are relatively tightly coupled.

/// tip | Inspired **FastAPI** to

Define extra validations for data types using the "default" value of model attributes. This improves editor support, and it was not available in Pydantic before.

This actually inspired updating parts of Pydantic, to support the same validation declaration style (all this functionality is now already available in Pydantic).

///

### [Hug](https://github.com/hugapi/hug) { #hug }

Hug was one of the first frameworks to implement the declaration of API parameter types using Python type hints. This was a great idea that inspired other tools to do the same.

It used custom types in its declarations instead of standard Python types, but it was still a huge step forward.

It also was one of the first frameworks to generate a custom schema declaring the whole API in JSON.

It was not based on a standard like OpenAPI and JSON Schema. So it wouldn't be straightforward to integrate it with other tools, like Swagger UI. But again, it was a very innovative idea.

It has an interesting, uncommon feature: using the same framework, it's possible to create APIs and also CLIs.

As it is based on the previous standard for synchronous Python web frameworks (WSGI), it can't handle Websockets and other things, although it still has high performance too.

/// note

Hug was created by Timothy Crosley, the same creator of [`isort`](https://github.com/timothycrosley/isort), a great tool to automatically sort imports in Python files.

///

/// tip | Ideas inspiring **FastAPI**

Hug inspired parts of APIStar, and was one of the tools I found most promising, alongside APIStar.

Hug helped inspire **FastAPI** to use Python type hints to declare parameters, and to generate a schema defining the API automatically.

Hug inspired **FastAPI** to declare a `response` parameter in functions to set headers and cookies.

///

### [APIStar](https://github.com/encode/apistar) (<= 0.5) { #apistar-0-5 }

Right before deciding to build **FastAPI** I found **APIStar** server. It had almost everything I was looking for and had a great design.

It was one of the first implementations of a framework using Python type hints to declare parameters and requests that I ever saw (before NestJS and Molten). I found it more or less at the same time as Hug. But APIStar used the OpenAPI standard.

It had automatic data validation, data serialization and OpenAPI schema generation based on the same type hints in several places.

Body schema definitions didn't use the same Python type hints like Pydantic, it was a bit more similar to Marshmallow, so, editor support wouldn't be as good, but still, APIStar was the best available option.

It had the best performance benchmarks at the time (only surpassed by Starlette).

At first, it didn't have an automatic API documentation web UI, but I knew I could add Swagger UI to it.

It had a dependency injection system. It required pre-registration of components, as other tools discussed above. But still, it was a great feature.

I was never able to use it in a full project, as it didn't have security integration, so, I couldn't replace all the features I was having with the full-stack generators based on Flask-apispec. I had in my backlog of projects to create a pull request adding that functionality.

But then, the project's focus shifted.

It was no longer an API web framework, as the creator needed to focus on Starlette.

Now APIStar is a set of tools to validate OpenAPI specifications, not a web framework.

/// note

APIStar was created by Tom Christie. The same guy that created:

* Django REST Framework
* Starlette (on which **FastAPI** is based)
* Uvicorn (used by Starlette and **FastAPI**)

///

/// tip | Inspired **FastAPI** to

Exist.

The idea of declaring multiple things (data validation, serialization and documentation) with the same Python types, that at the same time provided great editor support, was something I considered a brilliant idea.

And after searching for a long time for a similar framework and testing many different alternatives, APIStar was the best option available.

Then APIStar stopped existing as a server and Starlette was created, and was a new better foundation for such a system. That was the final inspiration to build **FastAPI**.

I consider **FastAPI** a "spiritual successor" to APIStar, while improving and increasing the features, typing system, and other parts, based on the learnings from all these previous tools.

///


docs/en/docs/alternatives.md::Used by **FastAPI** { #used-by-fastapi }::L402

# Doc: docs/en/docs/alternatives.md | Page: Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons } | Section: Used by **FastAPI** { #used-by-fastapi }
## Used by **FastAPI** { #used-by-fastapi }

### [Pydantic](https://docs.pydantic.dev/) { #pydantic }

Pydantic is a library to define data validation, serialization and documentation (using JSON Schema) based on Python type hints.

That makes it extremely intuitive.

It is comparable to Marshmallow. Although it's faster than Marshmallow in benchmarks. And as it is based on the same Python type hints, the editor support is great.

/// tip | **FastAPI** uses it to

Handle all the data validation, data serialization and automatic model documentation (based on JSON Schema).

**FastAPI** then takes that JSON Schema data and puts it in OpenAPI, apart from all the other things it does.

///

### [Starlette](https://www.starlette.dev/) { #starlette }

Starlette is a lightweight <dfn title="The new standard for building asynchronous Python web applications">ASGI</dfn> framework/toolkit, which is ideal for building high-performance asyncio services.

It is very simple and intuitive. It's designed to be easily extensible, and have modular components.

It has:

* Seriously impressive performance.
* WebSocket support.
* In-process background tasks.
* Startup and shutdown events.
* Test client built on HTTPX.
* CORS, GZip, Static Files, Streaming responses.
* Session and Cookie support.
* 100% test coverage.
* 100% type annotated codebase.
* Few hard dependencies.

Starlette is currently the fastest Python framework tested. Only surpassed by Uvicorn, which is not a framework, but a server.

Starlette provides all the basic web microframework functionality.

But it doesn't provide automatic data validation, serialization or documentation.

That's one of the main things that **FastAPI** adds on top, all based on Python type hints (using Pydantic). That, plus the dependency injection system, security utilities, OpenAPI schema generation, etc.

/// note | Technical Details

ASGI is a new "standard" being developed by Django core team members. It is still not a "Python standard" (a PEP), although they are in the process of doing that.

Nevertheless, it is already being used as a "standard" by several tools. This greatly improves interoperability, as you could switch Uvicorn for any other ASGI server (like Daphne or Hypercorn), or you could add ASGI compatible tools, like `python-socketio`.

///

/// tip | **FastAPI** uses it to

Handle all the core web parts. Adding features on top.

The class `FastAPI` itself inherits directly from the class `Starlette`.

So, anything that you can do with Starlette, you can do it directly with **FastAPI**, as it is basically Starlette on steroids.

///

### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn }

Uvicorn is a lightning-fast ASGI server, built on uvloop and httptools.

It is not a web framework, but a server. For example, it doesn't provide tools for routing by paths. That's something that a framework like Starlette (or **FastAPI**) would provide on top.

It is the recommended server for Starlette and **FastAPI**.

/// tip | **FastAPI** recommends it as

The main web server to run **FastAPI** applications.

You can also use the `--workers` command line option to have an asynchronous multi-process server.

Check more details in the [Deployment](deployment/index.md) section.

///


docs/en/docs/alternatives.md::Benchmarks and speed { #benchmarks-and-speed }::L483

# Doc: docs/en/docs/alternatives.md | Page: Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons } | Section: Benchmarks and speed { #benchmarks-and-speed }
## Benchmarks and speed { #benchmarks-and-speed }

To understand, compare, and see the difference between Uvicorn, Starlette and FastAPI, check the section about [Benchmarks](benchmarks.md).


docs/en/docs/async.md::Concurrency and async / await { #concurrency-and-async-await }::L1

# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: Concurrency and async / await { #concurrency-and-async-await }
# Concurrency and async / await { #concurrency-and-async-await }

Details about the `async def` syntax for *path operation functions* and some background about asynchronous code, concurrency, and parallelism.


docs/en/docs/async.md::In a hurry? { #in-a-hurry }::L5

# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: In a hurry? { #in-a-hurry }
## In a hurry? { #in-a-hurry }

TL;DR:

If you are using third party libraries that tell you to call them with `await`, like:

```Python
results = await some_library()
```

Then, declare your *path operation functions* with `async def` like:

```Python hl_lines="2"
@app.get('/')
async def read_results():
    results = await some_library()
    return results
```

/// note

You can only use `await` inside of functions created with `async def`.

///

---

If you are using a third party library that communicates with something (a database, an API, the file system, etc.) and doesn't have support for using `await`, (this is currently the case for most database libraries), then declare your *path operation functions* as normally, with just `def`, like:

```Python hl_lines="2"
@app.get('/')
def results():
    results = some_library()
    return results
```

---

If your application (somehow) doesn't have to communicate with anything else and wait for it to respond, use `async def`, even if you don't need to use `await` inside.

---

If you just don't know, use normal `def`.

---

**Note**: You can mix `def` and `async def` in your *path operation functions* as much as you need and define each one using the best option for you. FastAPI will do the right thing with them.

Anyway, in any of the cases above, FastAPI will still work asynchronously and be extremely fast.

But by following the steps above, it will be able to do some performance optimizations.


docs/en/docs/async.md::Technical Details { #technical-details }::L57

# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: Technical Details { #technical-details }
## Technical Details { #technical-details }

Modern versions of Python have support for **"asynchronous code"** using something called **"coroutines"**, with **`async` and `await`** syntax.

Let's see that phrase by parts in the sections below:

* **Asynchronous Code**
* **`async` and `await`**
* **Coroutines**


docs/en/docs/async.md::Asynchronous Code { #asynchronous-code }::L67

# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: Asynchronous Code { #asynchronous-code }
## Asynchronous Code { #asynchronous-code }

Asynchronous code just means that the language 💬 has a way to tell the computer / program 🤖 that at some point in the code, it 🤖 will have to wait for *something else* to finish somewhere else. Let's say that *something else* is called "slow-file" 📝.

So, during that time, the computer can go and do some other work, while "slow-file" 📝 finishes.

Then the computer / program 🤖 will come back every time it has a chance because it's waiting again, or whenever it 🤖 finishes all the work it had at that point. And it 🤖 will see if any of the tasks it was waiting for have already finished, doing whatever it had to do.

Next, it 🤖 takes the first task to finish (let's say, our "slow-file" 📝) and continues whatever it had to do with it.

That "wait for something else" normally refers to I/O operations that are relatively "slow" (compared to the speed of the processor and the RAM memory), like waiting for:

* the data from the client to be sent through the network
* the data sent by your program to be received by the client through the network
* the contents of a file on the disk to be read by the system and given to your program
* the contents your program gave to the system to be written to disk
* a remote API operation
* a database operation to finish
* a database query to return the results
* etc.

As the execution time is consumed mostly by waiting for I/O operations, they call them "I/O bound" operations.

It's called "asynchronous" because the computer / program doesn't have to be "synchronized" with the slow task, waiting for the exact moment that the task finishes, while doing nothing, to be able to take the task result and continue the work.

Instead of that, by being an "asynchronous" system, once finished, the task can wait in line a little bit (some microseconds) for the computer / program to finish whatever it went to do, and then come back to take the results and continue working with them.

For "synchronous" (contrary to "asynchronous") they commonly also use the term "sequential", because the computer / program follows all the steps in sequence before switching to a different task, even if those steps involve waiting.

### Concurrency and Burgers { #concurrency-and-burgers }

This idea of **asynchronous** code described above is also sometimes called **"concurrency"**. It is different from **"parallelism"**.

**Concurrency** and **parallelism** both relate to "different things happening more or less at the same time".

But the details between *concurrency* and *parallelism* are quite different.

To see the difference, imagine the following story about burgers:

### Concurrent Burgers { #concurrent-burgers }

You go with your crush to get fast food, you stand in line while the cashier takes the orders from the people in front of you. 😍

Then it's your turn, you place your order of 2 very fancy burgers for your crush and you. 🍔🍔

The cashier says something to the cook in the kitchen so they know they have to prepare your burgers (even though they are currently preparing the ones for the previous clients).

You pay. 💸

The cashier gives you the number of your turn.

While you are waiting, you go with your crush and pick a table, you sit and talk with your crush for a long time (as your burgers are very fancy and take some time to prepare).

As you are sitting at the table with your crush, while you wait for the burgers, you can spend that time admiring how awesome, cute and smart your crush is ✨😍✨.

While waiting and talking to your crush, from time to time, you check the number displayed on the counter to see if it's your turn already.

Then at some point, it finally is your turn. You go to the counter, get your burgers and come back to the table.

You and your crush eat the burgers and have a nice time. ✨

/// note

Beautiful illustrations by [Ketrina Thompson](https://www.instagram.com/ketrinadrawsalot). 🎨

///

---

Imagine you are the computer / program 🤖 in that story.

While you are at the line, you are just idle 😴, waiting for your turn, not doing anything very "productive". But the line is fast because the cashier is only taking the orders (not preparing them), so that's fine.

Then, when it's your turn, you do actual "productive" work, you process the menu, decide what you want, get your crush's choice, pay, check that you give the correct bill or card, check that you are charged correctly, check that the order has the correct items, etc.

But then, even though you still don't have your burgers, your work with the cashier is "on pause" ⏸, because you have to wait 🕙 for your burgers to be ready.

But as you go away from the counter and sit at the table with a number for your turn, you can switch 🔀 your attention to your crush, and "work" ⏯ 🤓 on that. Then you are again doing something very "productive" as is flirting with your crush 😍.

Then the cashier 💁 says "I'm finished with doing the burgers" by putting your number on the counter's display, but you don't jump like crazy immediately when the displayed number changes to your turn number. You know no one will steal your burgers because you have the number of your turn, and they have theirs.

So you wait for your crush to finish the story (finish the current work ⏯ / task being processed 🤓), smile gently and say that you are going for the burgers ⏸.

Then you go to the counter 🔀, to the initial task that is now finished ⏯, pick the burgers, say thanks and take them to the table. That finishes that step / task of interaction with the counter ⏹. That in turn, creates a new task, of "eating burgers" 🔀 ⏯, but the previous one of "getting burgers" is finished ⏹.

### Parallel Burgers { #parallel-burgers }

Now let's imagine these aren't "Concurrent Burgers", but "Parallel Burgers".

You go with your crush to get parallel fast food.

You stand in line while several (let's say 8) cashiers that at the same time are cooks take the orders from the people in front of you.

Everyone before you is waiting for their burgers to be ready before leaving the counter because each of the 8 cashiers goes and prepares the burger right away before getting the next order.

Then it's finally your turn, you place your order of 2 very fancy burgers for your crush and you.

You pay 💸.

The cashier goes to the kitchen.

You wait, standing in front of the counter 🕙, so that no one else takes your burgers before you do, as there are no numbers for turns.

As you and your crush are busy not letting anyone get in front of you and take your burgers whenever they arrive, you cannot pay attention to your crush. 😞

This is "synchronous" work, you are "synchronized" with the cashier/cook 👨🍳. You have to wait 🕙 and be there at the exact moment that the cashier/cook 👨🍳 finishes the burgers and gives them to you, or otherwise, someone else might take them.

Then your cashier/cook 👨🍳 finally comes back with your burgers, after a long time waiting 🕙 there in front of the counter.

You take your burgers and go to the table with your crush.

You just eat them, and you are done. ⏹

There was not much talk or flirting as most of the time was spent waiting 🕙 in front of the counter. 😞

/// note

Beautiful illustrations by [Ketrina Thompson](https://www.instagram.com/ketrinadrawsalot). 🎨

///

---

In this scenario of the parallel burgers, you are a computer / program 🤖 with two processors (you and your crush), both waiting 🕙 and dedicating their attention ⏯ to be "waiting on the counter" 🕙 for a long time.

The fast food store has 8 processors (cashiers/cooks). While the concurrent burgers store might have had only 2 (one cashier and one cook).

But still, the final experience is not the best. 😞

---

This would be the parallel equivalent story for burgers. 🍔

For a more "real life" example of this, imagine a bank.

Up to recently, most of the banks had multiple cashiers 👨💼👨💼👨💼👨💼 and a big line 🕙🕙🕙🕙🕙🕙🕙🕙.

All of the cashiers doing all the work with one client after the other 👨💼⏯.

And you have to wait 🕙 in the line for a long time or you lose your turn.

You probably wouldn't want to take your crush 😍 with you to run errands at the bank 🏦.

### Burger Conclusion { #burger-conclusion }

In this scenario of "fast food burgers with your crush", as there is a lot of waiting 🕙, it makes a lot more sense to have a concurrent system ⏸🔀⏯.

This is the case for most of the web applications.

Many, many users, but your server is waiting 🕙 for their not-so-good connection to send their requests.

And then waiting 🕙 again for the responses to come back.

This "waiting" 🕙 is measured in microseconds, but still, summing it all, it's a lot of waiting in the end.

That's why it makes a lot of sense to use asynchronous ⏸🔀⏯ code for web APIs.

This kind of asynchronicity is what made NodeJS popular (even though NodeJS is not parallel) and that's the strength of Go as a programming language.

And that's the same level of performance you get with **FastAPI**.

And as you can have parallelism and asynchronicity at the same time, you get higher performance than most of the tested NodeJS frameworks and on par with Go, which is a compiled language closer to C [(all thanks to Starlette)](https://www.techempower.com/benchmarks/#section=data-r17&hw=ph&test=query&l=zijmkf-1).

### Is concurrency better than parallelism? { #is-concurrency-better-than-parallelism }

Nope! That's not the moral of the story.

Concurrency is different than parallelism. And it is better in **specific** scenarios that involve a lot of waiting. Because of that, it generally is a lot better than parallelism for web application development. But not for everything.

So, to balance that out, imagine the following short story:

> You have to clean a big, dirty house.

*Yep, that's the whole story*.

---

There's no waiting 🕙 anywhere, just a lot of work to be done, in multiple places of the house.

You could have turns as in the burgers example, first the living room, then the kitchen, but as you are not waiting 🕙 for anything, just cleaning and cleaning, the turns wouldn't affect anything.

It would take the same amount of time to finish with or without turns (concurrency) and you would have done the same amount of work.

But in this case, if you could bring the 8 ex-cashier/cooks/now-cleaners, and each one of them (plus you) could take a zone of the house to clean it, you could do all the work in **parallel**, with the extra help, and finish much sooner.

In this scenario, each one of the cleaners (including you) would be a processor, doing their part of the job.

And as most of the execution time is taken by actual work (instead of waiting), and the work in a computer is done by a CPU, they call these problems "CPU bound".

---

Common examples of CPU bound operations are things that require complex math processing.

For example:

* **Audio** or **image processing**.
* **Computer vision**: an image is composed of millions of pixels, each pixel has 3 values / colors, processing that normally requires computing something on those pixels, all at the same time.
* **Machine Learning**: it normally requires lots of "matrix" and "vector" multiplications. Think of a huge spreadsheet with numbers and multiplying all of them together at the same time.
* **Deep Learning**: this is a sub-field of Machine Learning, so, the same applies. It's just that there is not a single spreadsheet of numbers to multiply, but a huge set of them, and in many cases, you use a special processor to build and / or use those models.

### Concurrency + Parallelism: Web + Machine Learning { #concurrency-parallelism-web-machine-learning }

With **FastAPI** you can take advantage of concurrency that is very common for web development (the same main attraction of NodeJS).

But you can also exploit the benefits of parallelism and multiprocessing (having multiple processes running in parallel) for **CPU bound** workloads like those in Machine Learning systems.

That, plus the simple fact that Python is the main language for **Data Science**, Machine Learning and especially Deep Learning, makes FastAPI a very good match for Data Science / Machine Learning web APIs and applications (among many others).

To see how to achieve this parallelism in production see the section about [Deployment](deployment/index.md).


docs/en/docs/async.md::`async` and `await` { #async-and-await }::L303

# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: `async` and `await` { #async-and-await }
## `async` and `await` { #async-and-await }

Modern versions of Python have a very intuitive way to define asynchronous code. This makes it look just like normal "sequential" code and do the "awaiting" for you at the right moments.

When there is an operation that will require waiting before giving the results and has support for these new Python features, you can code it like:

```Python
burgers = await get_burgers(2)
```

The key here is the `await`. It tells Python that it has to wait ⏸ for `get_burgers(2)` to finish doing its thing 🕙 before storing the results in `burgers`. With that, Python will know that it can go and do something else 🔀 ⏯ in the meanwhile (like receiving another request).

For `await` to work, it has to be inside a function that supports this asynchronicity. To do that, you just declare it with `async def`:

```Python hl_lines="1"
async def get_burgers(number: int):
    # Do some asynchronous stuff to create the burgers
    return burgers
```

...instead of `def`:

```Python hl_lines="2"
# This is not asynchronous
def get_sequential_burgers(number: int):
    # Do some sequential stuff to create the burgers
    return burgers
```

With `async def`, Python knows that, inside that function, it has to be aware of `await` expressions, and that it can "pause" ⏸ the execution of that function and go do something else 🔀 before coming back.

When you want to call an `async def` function, you have to "await" it. So, this won't work:

```Python
# This won't work, because get_burgers was defined with: async def
burgers = get_burgers(2)
```

---

So, if you are using a library that tells you that you can call it with `await`, you need to create the *path operation functions* that use it with `async def`, like in:

```Python hl_lines="2-3"
@app.get('/burgers')
async def read_burgers():
    burgers = await get_burgers(2)
    return burgers
```

### More technical details { #more-technical-details }

You might have noticed that `await` can only be used inside of functions defined with `async def`.

But at the same time, functions defined with `async def` have to be "awaited". So, functions with `async def` can only be called inside of functions defined with `async def` too.

So, about the egg and the chicken, how do you call the first `async` function?

If you are working with **FastAPI** you don't have to worry about that, because that "first" function will be your *path operation function*, and FastAPI will know how to do the right thing.

But if you want to use `async` / `await` without FastAPI, you can do it as well.

### Write your own async code { #write-your-own-async-code }

Starlette (and **FastAPI**) are based on [AnyIO](https://anyio.readthedocs.io/en/stable/), which makes it compatible with both Python's standard library [asyncio](https://docs.python.org/3/library/asyncio-task.html) and [Trio](https://trio.readthedocs.io/en/stable/).

In particular, you can directly use [AnyIO](https://anyio.readthedocs.io/en/stable/) for your advanced concurrency use cases that require more advanced patterns in your own code.

And even if you were not using FastAPI, you could also write your own async applications with [AnyIO](https://anyio.readthedocs.io/en/stable/) to be highly compatible and get its benefits (e.g. *structured concurrency*).

I created another library on top of AnyIO, as a thin layer on top, to improve a bit the type annotations and get better **autocompletion**, **inline errors**, etc. It also has a friendly introduction and tutorial to help you **understand** and write **your own async code**: [Asyncer](https://asyncer.tiangolo.com/). It would be particularly useful if you need to **combine async code with regular** (blocking/synchronous) code.

### Other forms of asynchronous code { #other-forms-of-asynchronous-code }

This style of using `async` and `await` is relatively new in the language.

But it makes working with asynchronous code a lot easier.

This same syntax (or almost identical) was also included recently in modern versions of JavaScript (in Browser and NodeJS).

But before that, handling asynchronous code was quite more complex and difficult.

In previous versions of Python, you could have used threads or [Gevent](https://www.gevent.org/). But the code is way more complex to understand, debug, and think about.

In previous versions of NodeJS / Browser JavaScript, you would have used "callbacks". Which leads to "callback hell".


docs/en/docs/async.md::Coroutines { #coroutines }::L388

# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: Coroutines { #coroutines }
## Coroutines { #coroutines }

**Coroutine** is just the very fancy term for the thing returned by an `async def` function. Python knows that it is something like a function, that it can start and that it will end at some point, but that it might be paused ⏸ internally too, whenever there is an `await` inside of it.

But all this functionality of using asynchronous code with `async` and `await` is many times summarized as using "coroutines". It is comparable to the main key feature of Go, the "Goroutines".


docs/en/docs/async.md::Conclusion { #conclusion }::L394

# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: Conclusion { #conclusion }
## Conclusion { #conclusion }

Let's see the same phrase from above:

> Modern versions of Python have support for **"asynchronous code"** using something called **"coroutines"**, with **`async` and `await`** syntax.

That should make more sense now. ✨

All that is what powers FastAPI (through Starlette) and what makes it have such an impressive performance.


docs/en/docs/async.md::Very Technical Details { #very-technical-details }::L404

# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: Very Technical Details { #very-technical-details }
## Very Technical Details { #very-technical-details }

/// warning

You can probably skip this.

These are very technical details of how **FastAPI** works underneath.

If you have quite some technical knowledge (coroutines, threads, blocking, etc.) and are curious about how FastAPI handles `async def` vs normal `def`, go ahead.

///

### Path operation functions { #path-operation-functions }

When you declare a *path operation function* with normal `def` instead of `async def`, it is run in an external threadpool that is then awaited, instead of being called directly (as it would block the server).

If you are coming from another async framework that does not work in the way described above and you are used to defining trivial compute-only *path operation functions* with plain `def` for a tiny performance gain (about 100 nanoseconds), please note that in **FastAPI** the effect would be quite opposite. In these cases, it's better to use `async def` unless your *path operation functions* use code that performs blocking I/O.

Still, in both situations, chances are that **FastAPI** will [still be faster](index.md#performance) than (or at least comparable to) your previous framework.

### Dependencies { #dependencies }

The same applies for [dependencies](tutorial/dependencies/index.md). If a dependency is a standard `def` function instead of `async def`, it is run in the external threadpool.

### Sub-dependencies { #sub-dependencies }

You can have multiple dependencies and [sub-dependencies](tutorial/dependencies/sub-dependencies.md) requiring each other (as parameters of the function definitions), some of them might be created with `async def` and some with normal `def`. It would still work, and the ones created with normal `def` would be called on an external thread (from the threadpool) instead of being "awaited".

### Other utility functions { #other-utility-functions }

Any other utility function that you call directly can be created with normal `def` or `async def` and FastAPI won't affect the way you call it.

This is in contrast to the functions that FastAPI calls for you: *path operation functions* and dependencies.

If your utility function is a normal function with `def`, it will be called directly (as you write it in your code), not in a threadpool, if the function is created with `async def` then you should `await` that function when you call it in your code.

---

Again, these are very technical details that would probably be useful if you came searching for them.

Otherwise, you should be good with the guidelines from the section above: In a hurry?.


docs/en/docs/benchmarks.md::Benchmarks { #benchmarks }::L1

# Doc: docs/en/docs/benchmarks.md | Page: Benchmarks { #benchmarks } | Section: Benchmarks { #benchmarks }
# Benchmarks { #benchmarks }

Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as [one of the fastest Python frameworks available](https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7), only below Starlette and Uvicorn themselves (used internally by FastAPI).

But when checking benchmarks and comparisons you should keep the following in mind.


docs/en/docs/benchmarks.md::Benchmarks and speed { #benchmarks-and-speed }::L7

# Doc: docs/en/docs/benchmarks.md | Page: Benchmarks { #benchmarks } | Section: Benchmarks and speed { #benchmarks-and-speed }
## Benchmarks and speed { #benchmarks-and-speed }

When you check the benchmarks, it is common to see several tools of different types compared as equivalent.

Specifically, to see Uvicorn, Starlette and FastAPI compared together (among many other tools).

The simpler the problem solved by the tool, the better performance it will get. And most of the benchmarks don't test the additional features provided by the tool.

The hierarchy is like:

* **Uvicorn**: an ASGI server
    * **Starlette**: (uses Uvicorn) a web microframework
        * **FastAPI**: (uses Starlette) an API microframework with several additional features for building APIs, with data validation, etc.

* **Uvicorn**:
    * Will have the best performance, as it doesn't have much extra code apart from the server itself.
    * You wouldn't write an application in Uvicorn directly. That would mean that your code would have to include more or less, at least, all the code provided by Starlette (or **FastAPI**). And if you did that, your final application would have the same overhead as having used a framework and minimizing your app code and bugs.
    * If you are comparing Uvicorn, compare it against Daphne, Hypercorn, uWSGI, etc. Application servers.
* **Starlette**:
    * Will have the next best performance, after Uvicorn. In fact, Starlette uses Uvicorn to run. So, it probably can only get "slower" than Uvicorn by having to execute more code.
    * But it provides you the tools to build simple web applications, with routing based on paths, etc.
    * If you are comparing Starlette, compare it against Sanic, Flask, Django, etc. Web frameworks (or microframeworks).
* **FastAPI**:
    * The same way that Starlette uses Uvicorn and cannot be faster than it, **FastAPI** uses Starlette, so it cannot be faster than it.
    * FastAPI provides more features on top of Starlette. Features that you almost always need when building APIs, like data validation and serialization. And by using it, you get automatic documentation for free (the automatic documentation doesn't even add overhead to running applications, it is generated on startup).
    * If you didn't use FastAPI and used Starlette directly (or another tool, like Sanic, Flask, Responder, etc) you would have to implement all the data validation and serialization yourself. So, your final application would still have the same overhead as if it was built using FastAPI. And in many cases, this data validation and serialization is the biggest amount of code written in applications.
    * So, by using FastAPI you are saving development time, bugs, lines of code, and you would probably get the same performance (or better) you would if you didn't use it (as you would have to implement it all in your code).
    * If you are comparing FastAPI, compare it against a web application framework (or set of tools) that provides data validation, serialization and documentation, like Flask-apispec, NestJS, Molten, etc. Frameworks with integrated automatic data validation, serialization and documentation.


# Doc: docs/en/docs/contributing.md | Page: Contributing | Section: Contributing
# Contributing

First, you might want to see the basic ways to [help FastAPI and get help](help-fastapi.md).


# Doc: docs/en/docs/contributing.md | Page: Contributing | Section: Developing
## Developing

To contribute code to the project, please follow the guidelines in [tiangolo.com - Contributing](https://tiangolo.com/open-source/contributing/).


docs/en/docs/deployment/cloud.md::Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers }::L1

# Doc: docs/en/docs/deployment/cloud.md | Page: Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers } | Section: Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers }
# Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers }

You can use virtually **any cloud provider** to deploy your FastAPI application.

In most of the cases, the main cloud providers have guides to deploy FastAPI with them.


docs/en/docs/deployment/cloud.md::FastAPI Cloud { #fastapi-cloud }::L7

# Doc: docs/en/docs/deployment/cloud.md | Page: Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers } | Section: FastAPI Cloud { #fastapi-cloud }
## FastAPI Cloud { #fastapi-cloud }

**[FastAPI Cloud](https://fastapicloud.com)** is built by the same author and team behind **FastAPI**.

It streamlines the process of **building**, **deploying**, and **accessing** an API with minimal effort.

It brings the same **developer experience** of building apps with FastAPI to **deploying** them to the cloud. 🎉

FastAPI Cloud is the primary sponsor and funding provider for the *FastAPI and friends* open source projects. ✨


docs/en/docs/deployment/cloud.md::Cloud Providers - Sponsors { #cloud-providers-sponsors }::L17

# Doc: docs/en/docs/deployment/cloud.md | Page: Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers } | Section: Cloud Providers - Sponsors { #cloud-providers-sponsors }
## Cloud Providers - Sponsors { #cloud-providers-sponsors }

Some other cloud providers ✨ [**sponsor FastAPI**](https://github.com/sponsors/tiangolo) ✨ too. 🙇

You might also want to consider them to follow their guides and try their services:

* [Render](https://docs.render.com/deploy-fastapi?utm_source=deploydoc&utm_medium=referral&utm_campaign=fastapi)
* [Railway](https://docs.railway.com/guides/fastapi?utm_medium=integration&utm_source=docs&utm_campaign=fastapi)