Background Tasks¶

You can define background tasks to be runafter returning a response.

This is useful for operations that need to happen after a request, but that the client doesn't really have to be waiting for the operation to complete before receiving the response.

This includes, for example:

• Email notifications sent after performing an action:
  • As connecting to an email server and sending an email tends to be "slow" (several seconds), you can return the response right away and send the email notification in the background.
• Processing data:
  • For example, let's say you receive a file that must go through a slow process, you can return a response of "Accepted" (HTTP 202) and process the file in the background.

UsingBackgroundTasks¶

First, importBackgroundTasks and define a parameter in yourpath operation function with a type declaration ofBackgroundTasks:

fromfastapiimportBackgroundTasks,FastAPIapp=FastAPI()defwrite_notification(email:str,message=""):withopen("log.txt",mode="w")asemail_file:content=f"notification for{email}:{message}"email_file.write(content)@app.post("/send-notification/{email}")asyncdefsend_notification(email:str,background_tasks:BackgroundTasks):background_tasks.add_task(write_notification,email,message="some notification")return{"message":"Notification sent in the background"}

FastAPI will create the object of typeBackgroundTasks for you and pass it as that parameter.

Create a task function¶

Create a function to be run as the background task.

It is just a standard function that can receive parameters.

It can be anasync def or normaldef function,FastAPI will know how to handle it correctly.

In this case, the task function will write to a file (simulating sending an email).

And as the write operation doesn't useasync andawait, we define the function with normaldef:

fromfastapiimportBackgroundTasks,FastAPIapp=FastAPI()defwrite_notification(email:str,message=""):withopen("log.txt",mode="w")asemail_file:content=f"notification for{email}:{message}"email_file.write(content)@app.post("/send-notification/{email}")asyncdefsend_notification(email:str,background_tasks:BackgroundTasks):background_tasks.add_task(write_notification,email,message="some notification")return{"message":"Notification sent in the background"}

Add the background task¶

Inside of yourpath operation function, pass your task function to thebackground tasks object with the method.add_task():

fromfastapiimportBackgroundTasks,FastAPIapp=FastAPI()defwrite_notification(email:str,message=""):withopen("log.txt",mode="w")asemail_file:content=f"notification for{email}:{message}"email_file.write(content)@app.post("/send-notification/{email}")asyncdefsend_notification(email:str,background_tasks:BackgroundTasks):background_tasks.add_task(write_notification,email,message="some notification")return{"message":"Notification sent in the background"}

.add_task() receives as arguments:

• A task function to be run in the background (write_notification).
• Any sequence of arguments that should be passed to the task function in order (email).
• Any keyword arguments that should be passed to the task function (message="some notification").

Dependency Injection¶

UsingBackgroundTasks also works with the dependency injection system, you can declare a parameter of typeBackgroundTasks at multiple levels: in apath operation function, in a dependency (dependable), in a sub-dependency, etc.

FastAPI knows what to do in each case and how to reuse the same object, so that all the background tasks are merged together and are run in the background afterwards:

fromtypingimportAnnotatedfromfastapiimportBackgroundTasks,Depends,FastAPIapp=FastAPI()defwrite_log(message:str):withopen("log.txt",mode="a")aslog:log.write(message)defget_query(background_tasks:BackgroundTasks,q:str|None=None):ifq:message=f"found query:{q}\n"background_tasks.add_task(write_log,message)returnq@app.post("/send-notification/{email}")asyncdefsend_notification(email:str,background_tasks:BackgroundTasks,q:Annotated[str,Depends(get_query)]):message=f"message to{email}\n"background_tasks.add_task(write_log,message)return{"message":"Message sent"}

fromfastapiimportBackgroundTasks,Depends,FastAPIapp=FastAPI()defwrite_log(message:str):withopen("log.txt",mode="a")aslog:log.write(message)defget_query(background_tasks:BackgroundTasks,q:str|None=None):ifq:message=f"found query:{q}\n"background_tasks.add_task(write_log,message)returnq@app.post("/send-notification/{email}")asyncdefsend_notification(email:str,background_tasks:BackgroundTasks,q:str=Depends(get_query)):message=f"message to{email}\n"background_tasks.add_task(write_log,message)return{"message":"Message sent"}

In this example, the messages will be written to thelog.txt fileafter the response is sent.

If there was a query in the request, it will be written to the log in a background task.

And then another background task generated at thepath operation function will write a message using theemail path parameter.

Technical Details¶

The classBackgroundTasks comes directly fromstarlette.background.

It is imported/included directly into FastAPI so that you can import it fromfastapi and avoid accidentally importing the alternativeBackgroundTask (without thes at the end) fromstarlette.background.

By only usingBackgroundTasks (and notBackgroundTask), it's then possible to use it as apath operation function parameter and haveFastAPI handle the rest for you, just like when using theRequest object directly.

It's still possible to useBackgroundTask alone in FastAPI, but you have to create the object in your code and return a StarletteResponse including it.

You can see more details inStarlette's official docs for Background Tasks.

Caveat¶

If you need to perform heavy background computation and you don't necessarily need it to be run by the same process (for example, you don't need to share memory, variables, etc), you might benefit from using other bigger tools likeCelery.

They tend to require more complex configurations, a message/job queue manager, like RabbitMQ or Redis, but they allow you to run background tasks in multiple processes, and especially, in multiple servers.

But if you need to access variables and objects from the sameFastAPI app, or you need to perform small background tasks (like sending an email notification), you can simply just useBackgroundTasks.

Recap¶

Import and useBackgroundTasks with parameters inpath operation functions and dependencies to add background tasks.