skip to content

Given what happens to pending BackgroundTasks when a Uvicorn worker shuts down, how would you decide which FastAPI jobs move to a task queue such as Celery?

level: principalimportance: should knowfreq 40%

answer

  1. where the task lives: one process's memory
  2. SIGTERM, then the grace period
  3. --timeout-graceful-shutdown
  4. retries, status, separate scaling

basics

~20 s

BackgroundTasks lives in one worker's memory: Uvicorn waits for it on SIGTERM, but a kill, crash or shutdown timeout loses it unretried. Keep short, loss-tolerant follow-ups there; queue work that must happen or runs long.

solid answer

~50 s

A `BackgroundTasks` list exists only inside the request's handling in one worker process. On SIGTERM, Uvicorn stops accepting connections, logs `Waiting for background tasks to complete.` and waits, by default with no limit; `--timeout-graceful-shutdown` cancels whatever is still running when it expires. A container platform kills the process when its own grace period ends, and a crash or out-of-memory kill gives no warning at all; queued tasks are then gone, with no record and no retry. So I keep `BackgroundTasks` for short, best-effort follow-ups whose loss is tolerable, and move anything that must happen, needs retries or status, runs longer than the shutdown window, or needs its own scaling to a task queue such as Celery. Work that must never be lost but is quick, like an audit row, I write inside the request instead.

code

bash · 1 line
bash
uvicorn main:app --workers 4 --timeout-graceful-shutdown 20

go deeper

for a junior

Remember that background tasks live in the memory of the worker that served the request, so a restart or crash can lose them.

for a middle

Describe Uvicorn's shutdown: stop accepting connections, wait for running tasks, and cancel them only when --timeout-graceful-shutdown expires.

for a senior

Connect it to operations: deploys, platform grace periods, crashes and out-of-memory kills each lose queued tasks silently, and the shutdown timeout should sit below the platform's grace period.

for a principal

Own the rule for the team: which jobs are loss-tolerant enough for BackgroundTasks, which go to a queue, and which belong inside the request, and weigh a queue's operating cost.

## What a background task actually is In FastAPI a `BackgroundTasks` entry is a function reference and its arguments, held **in memory** inside the request currently being handled by **one worker process**. It is awaited after the response, as the last part of that request's handling. There is: - **no persistence**: nothing is written anywhere before it runs; - **no retry**: an exception ends it, and the remaining tasks of that request, with a log line; - **no status or result**: nobody can ask whether it ran; - **no separate capacity**: `def` tasks share the anyio thread limiter with `def` endpoints, `async def` tasks share the event loop, and default-scope yield dependencies stay open until the tasks end. Everything that follows comes from those four facts. ## What happens when the worker shuts down In Uvicorn 0.54, shutdown on SIGTERM goes like this: 1. It logs `Shutting down`, stops accepting connections and closes idle ones. 2. If requests still have tasks running, it logs `Waiting for background tasks to complete. (CTRL+C to force quit)` and waits. 3. By default (`timeout_graceful_shutdown` unset) it waits **without a limit**. With `--timeout-graceful-shutdown 20` it cancels what is still running after 20 seconds and logs `Cancel 1 running task(s), timeout graceful shutdown exceeded`; tasks not yet started in that list never run. 4. Only then does it run the app's `lifespan` shutdown. `fastapi run` exposes no option for that timeout; running Uvicorn directly does. Outside the process, loss is more likely than these steps suggest: - **A container platform** sends SIGTERM, then kills the process once its own grace period ends, mid-task or not. - **A crash or an out-of-memory kill** ends the process at once; nothing is waited for or logged. - **A second Ctrl+C** in a terminal forces the exit. - **Uvicorn's `--limit-max-requests`** makes a worker exit after a request count; it goes through the same graceful shutdown, so it waits. Each deployment restarts every worker, so a team that deploys many times a day is exercising this path many times a day. Running several workers with `fastapi run --workers` does not help: each task stays in the process that served its request, and no other worker can take it over. ## The decision a lead has to make There is no single right line; it depends on what a lost or failed job costs. A workable split for a sign-up flow: | Job | Where | Why | |---|---|---| | welcome email | `BackgroundTasks` (or a queue, at scale) | short, and a lost one can be re-sent on request | | audit row | inside the request, before responding | quick, and must not be lost | | charge a card, provision an account in another system | task queue | must happen once, needs retries and status | | generate a large report, embed documents for a model | task queue | long or CPU-heavy, should scale separately | Questions that decide it: 1. **Can the job be lost?** If not, `BackgroundTasks` is out. 2. **Must it be retried on failure?** A queue offers retries with backoff; in-process tasks do not. 3. **How long does it run?** Longer than the shutdown window means it will be cut off on deploys. 4. **Does it compete with requests?** CPU or thread-heavy work slows the same worker's requests. 5. **Does anyone need its status?** A queue can report state; an in-process task cannot. ## The cost on the other side A task queue such as Celery brings a broker, worker processes, serialization of arguments, monitoring and its own deployment, and it adds a failure mode: a job published before the database transaction commits can run against data that does not exist yet. That cost is worth paying for jobs that matter, and it is overhead for a best-effort notification. Many teams settle on a convention: `BackgroundTasks` only for idempotent, loss-tolerant follow-ups that finish in a few seconds, every task catching and logging its own errors, `--timeout-graceful-shutdown` set below the platform's grace period, and everything else through the queue.

  • Does running FastAPI with several workers make BackgroundTasks safer?
    No. Each task runs in the worker process that served its request, and no other worker can take it over. More workers spread the load, but a restart or crash still loses whatever the affected worker had queued.
  • Why set --timeout-graceful-shutdown below the container platform's grace period?
    So Uvicorn decides what to cancel, logs `Cancel N running task(s)` and still runs the `lifespan` shutdown before the platform kills the process. Without it Uvicorn waits indefinitely and the platform's kill cuts everything off, shutdown hooks included, with no record of what was lost.

BackgroundTasks is a sticky note on the cashier's till: quick to write and handled right after the customer leaves, but gone if the shop is shut in a hurry. A task queue is the order book in the back office: slower to fill in, yet it survives closing time and someone works through it.

  • FastAPI persists pending background tasks and reruns them after a restart
  • Uvicorn cancels background tasks immediately when it receives SIGTERM
  • BackgroundTasks retries a task that raised until it succeeds
  • With several workers, another worker picks up a crashed worker's tasks
  • Anything slow belongs in BackgroundTasks because the client no longer waits