In FastAPI, when should a path operation function be declared with plain def, and when with async def?
answer
- what the function waits on
- await needs an awaitable library
- blocking library means plain def
- def goes to a worker thread
basics
~20 sUse async def when the function awaits an async library or does no blocking I/O; use plain def when it calls a blocking library, because FastAPI runs def functions on a worker thread. When unsure, def is the safer choice.
solid answer
~40 sThe choice follows what the function waits on. If it calls a library you `await`, such as an async HTTP client or an async database driver, it has to be `async def`, because `await` is only legal there. If it calls a blocking library, such as a synchronous SDK or a classic database driver, declare it with plain `def`: FastAPI then runs it through `run_in_threadpool` on an anyio worker thread, and the event loop keeps serving other requests. If it does no I/O at all, `async def` skips the thread hand-off. Dependencies follow the same rule, and one app can mix both kinds freely. The mistake to avoid is `async def` wrapped around a blocking call: it runs on the event loop and stalls every request on that worker.
code
python · 28 linesimport asyncio
import time
from fastapi import FastAPI
app = FastAPI()
def blocking_sdk_quote(symbol: str) -> float:
time.sleep(0.2) # stands in for a synchronous SDK call
return 101.5
async def async_client_quote(symbol: str) -> float:
await asyncio.sleep(0.2) # stands in for an awaitable client call
return 101.5
@app.get("/quotes/sync/{symbol}")
def quote_sync(symbol: str):
# plain def: FastAPI runs it on an anyio worker thread
return {"symbol": symbol, "price": blocking_sdk_quote(symbol)}
@app.get("/quotes/async/{symbol}")
async def quote_async(symbol: str):
# async def: runs on the event loop, so it only awaits
return {"symbol": symbol, "price": await async_client_quote(symbol)}go deeper
Recall the four cases: an awaited library means async def, a blocking library means def, nothing to wait on means async def, and def when unsure.
Explain where each kind runs: def functions go through run_in_threadpool to anyio worker threads, async def functions are awaited on the event loop, and dependencies follow the same rule.
Spot async def wrapped around a blocking SDK in code review and explain what it does to latency for every other request on that worker.
Set the team convention: which client libraries async code may use, and how review or load tests catch blocking calls in async def before production.
## The rule in one table FastAPI lets you write a **path operation function** (the function under `@app.get`, `@app.post` and the rest) either as a plain `def` or as an `async def`. The keyword is not a style preference: it tells FastAPI **where to run the function**. FastAPI's own docs reduce the choice to four cases. | What the function does | Declare it with | Why | |---|---|---| | Calls a library you must `await` | `async def` | `await` is only legal inside `async def` | | Calls a blocking library (no `await` support) | `def` | FastAPI runs it on a worker thread, off the event loop | | Waits on nothing, just computes a small result | `async def` | avoids a needless hand-off to a thread | | You are not sure what the library does | `def` | the safe default: a blocking call cannot freeze the loop | You can **mix both kinds** in one application, endpoint by endpoint. FastAPI handles each one separately. ## What FastAPI does with each kind A FastAPI app, served by Uvicorn, runs one **event loop** per worker process: a single thread that switches between requests whenever the running code reaches an `await`. - An `async def` path operation is **awaited directly on that event loop**. While it awaits an async client, the loop serves other requests. While it runs ordinary code, nothing else on that loop runs. - A plain `def` path operation is handed to `run_in_threadpool` (re-exported by `fastapi.concurrency` from Starlette), which calls `anyio.to_thread.run_sync`. The function runs on an **anyio worker thread**, and the event loop awaits the result, free to serve other requests meanwhile. That is why a blocking library belongs in `def`: the blocking happens on a worker thread, not on the loop. ## Dependencies follow the same rule Functions you pass to `Depends` are classified the same way. A `def` dependency runs on a worker thread; an `async def` dependency is awaited on the loop. An endpoint of either kind can depend on both kinds, so choose **per function**, by what that function calls: - a dependency that opens a session with a synchronous database driver: `def`; - a dependency that awaits an async cache client: `async def`; - a dependency that only reads a header and returns it: `async def` is fine. Sub-dependencies work the same way. A chain where an `async def` dependency depends on a `def` one, which depends on another `async def` one, is legal: FastAPI resolves them in order, awaiting the async ones on the loop and sending the sync ones to the thread pool, and hands each result to the next. ## Functions you call yourself The rule applies only to functions **FastAPI calls for you**: path operations and dependencies. A helper you call from your own code runs exactly where you call it: 1. a plain `def` helper called from an `async def` endpoint runs **on the event loop**, inside that endpoint; 2. a plain `def` helper called from a `def` endpoint runs on that endpoint's worker thread; 3. an `async def` helper must be awaited by an `async def` caller. FastAPI does not inspect a function body for blocking calls. Declaring the endpoint `async def` and calling a blocking helper from it is the same as calling the blocking library directly. ## The two mistakes - **`async def` around a blocking call.** The call runs on the event loop, so every other request on that worker waits until it returns. This is the expensive mistake: it shows up as latency on unrelated endpoints, not just the slow one. - **`def` everywhere "to be safe" for trivial code.** It is not wrong, but each call costs a hand-off to a worker thread and back, and the worker threads are a limited pool (anyio's default limiter allows 40 at once). FastAPI's docs note that for compute-only functions this makes `def` slightly slower, not faster. ## A worked example An endpoint that calls a synchronous SDK uses `def`; one that awaits an async client uses `async def`: ```python @app.get("/quotes/sync/{symbol}") def quote_sync(symbol: str): return {"price": blocking_sdk_quote(symbol)} # worker thread @app.get("/quotes/async/{symbol}") async def quote_async(symbol: str): return {"price": await async_client_quote(symbol)} # event loop ``` If one function needs both an awaitable call and a blocking one, make it `async def` and push the blocking call to a worker thread yourself with `await run_in_threadpool(func, ...)`.
- Is a def path operation slower than an async def one in FastAPI?For trivial compute-only functions, slightly: a `def` function pays a hand-off to an anyio worker thread and back, which FastAPI's docs describe as the opposite of the tiny gain people expect from `def` in other frameworks. For blocking I/O the comparison does not apply, because `async def` would freeze the event loop.
- Can one FastAPI endpoint depend on both def and async def dependencies?Yes. FastAPI classifies each dependency on its own: an `async def` dependency is awaited on the event loop and a `def` one runs on a worker thread, whatever the endpoint itself is declared with. Pick each dependency's keyword by what that dependency calls.
- What if one FastAPI endpoint needs an awaitable client and a blocking library?Declare it `async def` so it can `await` the async client, and send the blocking call to a worker thread yourself with `await run_in_threadpool(func, *args)` from `fastapi.concurrency`, or `anyio.to_thread.run_sync`. Both use the same anyio worker threads FastAPI uses for `def` functions.
- async def always makes a FastAPI endpoint faster than def
- A def path operation blocks the whole FastAPI server while it runs
- FastAPI moves blocking calls inside async def onto a thread automatically
- Every dependency must use the same keyword as its endpoint
- Any def helper an endpoint calls also gets its own worker thread