skip to content

In FastAPI, when a dependency and the endpoint both add tasks to BackgroundTasks, in what order and on which threads do they run?

level: middleimportance: must knowfreq 50%

answer

  1. one object per request
  2. dependencies resolve before the endpoint body
  3. awaited one at a time
  4. run_in_threadpool for def

basics

~20 s

Both get the same per-request BackgroundTasks, so the tasks run as one list in the order add_task was called, one at a time, after the response: def tasks on a thread-pool thread, async def tasks on the event loop.

solid answer

~40 s

FastAPI creates one `BackgroundTasks` object per request and passes that same object to every endpoint, dependency and sub-dependency that declares the type, so all `add_task` calls append to one list. Dependencies are resolved before the endpoint body runs, so a task a dependency adds normally comes before the endpoint's. After the response has been sent, the list is walked in order and each task is awaited before the next starts; no two tasks of one request run at the same time. A `def` task goes through Starlette's `run_in_threadpool`, using one of anyio's worker threads, while an `async def` task is awaited on the event loop, where a blocking call such as `time.sleep` stalls every request that worker is serving.

code

python · 25 lines
python
from typing import Annotated

from fastapi import BackgroundTasks, Depends, FastAPI

app = FastAPI()


async def write_audit_line(event: str) -> None:
    print(f"1. audit: {event}")  # async def: awaited on the event loop


def send_welcome_email(email: str) -> None:
    print(f"2. email: {email}")  # def: run in a thread-pool worker thread


def audit_signup(background_tasks: BackgroundTasks) -> None:
    # resolved before the endpoint body runs, so this task is queued first
    background_tasks.add_task(write_audit_line, "signup")


@app.post("/signup", status_code=201, dependencies=[Depends(audit_signup)])
async def signup(email: str, background_tasks: BackgroundTasks):
    # the same BackgroundTasks object the dependency received
    background_tasks.add_task(send_welcome_email, email)
    return {"email": email}

go deeper

for a junior

Remember that the endpoint and its dependencies share one BackgroundTasks object and the tasks run after the response, in the order they were added.

for a middle

Explain the sequential loop, why dependencies queue first, and the split between run_in_threadpool for def tasks and the event loop for async def tasks.

for a senior

Show how one slow or blocking task hurts others: it delays the rest of the list, holds a thread-pool slot shared with def endpoints, or freezes the loop if written as async def.

for a principal

Decide whether a team relies on implicit ordering between dependencies and endpoints, or requires order-sensitive follow-ups to be queued from a single place.

## One list per request `BackgroundTasks` is a **request-scoped object**. When FastAPI resolves a request, it creates at most one instance and hands that **same instance** to every place that declares a parameter of that type: - the path operation function; - a dependency or sub-dependency declared with `Depends`; - a dependency listed in the decorator's `dependencies=[...]`, a router's or the app's. Each `add_task` call appends a recorded call to the instance's internal `tasks` list. The FastAPI documentation describes this as all the background tasks being *merged together* and run afterwards. There is no per-dependency list and no priority: the list order is simply the order in which `add_task` was executed. ## Why the dependency's task usually comes first FastAPI resolves the whole dependency graph **before** it calls the endpoint. A dependency that queues an audit line therefore calls `add_task` before the endpoint body gets a chance to queue the welcome email: ```python from fastapi import BackgroundTasks, Depends, FastAPI app = FastAPI() async def write_audit_line(event: str) -> None: ... def send_welcome_email(email: str) -> None: ... def audit_signup(background_tasks: BackgroundTasks) -> None: background_tasks.add_task(write_audit_line, "signup") @app.post("/signup", status_code=201, dependencies=[Depends(audit_signup)]) async def signup(email: str, background_tasks: BackgroundTasks): background_tasks.add_task(send_welcome_email, email) return {"email": email} ``` After the response, `write_audit_line` runs first and `send_welcome_email` second. If the order matters for correctness, make it explicit by queuing both from one place rather than relying on how the graph happens to resolve. ## How the list is executed Once the status line, headers and body have been sent, the response object awaits its background list: 1. Take the next recorded call. 2. If the function is a coroutine function (`async def`), await it on the event loop. 3. Otherwise, call it through `run_in_threadpool`, which hands it to `anyio.to_thread.run_sync` and waits for the worker thread to finish. 4. Move to the next call only when this one has returned. So the tasks of **one request are strictly sequential**. Tasks belonging to different requests are independent of each other: each request awaits its own list, so they interleave on the event loop like any other request handling. | Task written as | Where it runs | What a blocking call does | |---|---|---| | `def` | an anyio worker thread, via `run_in_threadpool` | holds one thread-pool slot until it returns | | `async def` | the event loop of that worker process | freezes every request on that worker | ## Consequences worth stating in an interview - **A slow first task delays the second.** A mail-server call that takes ten seconds pushes the audit line ten seconds back. - **A failing task ends the list.** An exception propagates out of the loop, so later tasks of that request are skipped. - **`def` tasks compete with `def` endpoints.** They draw on the same anyio default thread limiter as `def` path operations and dependencies, so a burst of slow `def` tasks can starve ordinary requests of threads. - **`async def` is not a free upgrade.** An `async def` task must only await non-blocking calls; a synchronous client library inside it blocks the loop exactly as it would inside an `async def` endpoint. - **Choose the function style by what it calls**, not by habit: blocking I/O in a `def` task, awaitable I/O in an `async def` task. ## Picking `def` or `async def` for a task The rule is the same one FastAPI applies to endpoints, and it is decided by what the task calls, not by what the endpoint is: - a task that uses a **synchronous** mail or HTTP client library should be a plain `def`, so it lands on a worker thread; - a task that only awaits **asynchronous** clients can be `async def` and avoids a thread hop; - a task that mixes both can be `async def` and push the blocking part to a thread with `anyio.to_thread.run_sync`. An `async def` endpoint may queue a `def` task and the reverse; each task is dispatched on its own definition. ## Checking it in a test `fastapi.testclient.TestClient` returns from `client.post(...)` only after the request's tasks have run, so a test can assert on their side effects directly after the call. That makes the order easy to pin down with a list the tasks append to.

  • Do the background tasks of two different FastAPI requests wait for each other?
    No. Each request awaits its own `BackgroundTasks` list after its own response, so tasks from different requests interleave on the event loop like any other request work. They still share resources: `def` tasks draw threads from the same anyio limiter, and a blocking `async def` task stalls everything on that worker.
  • How would you run two independent FastAPI background tasks concurrently instead of one after the other?
    `BackgroundTasks` itself always runs them in sequence. Queue a single `async def` task that starts both with an anyio task group and awaits them; if they are blocking, offload each with `anyio.to_thread.run_sync` inside that group.

  • Each add_task call starts its own thread, so the tasks run in parallel
  • The endpoint's tasks always run before tasks added by its dependencies
  • An async def task can call blocking libraries safely because the response is already sent
  • Every dependency receives its own BackgroundTasks list, run separately
  • def background tasks use a separate thread pool from def endpoints