Stopping Loops on Shutdown in FastAPI: A Complete Guide (2026)

When building web applications with FastAPI, you might encounter scenarios where long-running or endless loops are necessary, such as maintaining a connection or continuously processing data. However, managing these loops during application shutdown is crucial to ensure a clean and efficient shutdown process.

Key Takeaways

• Learn how to properly handle loop termination in FastAPI using shutdown events.
• Understand the importance of clean shutdowns to prevent resource leaks.
• Implement a practical example of stopping an asynchronous loop.
• Explore common pitfalls and troubleshooting techniques.

This tutorial will guide you through the process of stopping an endless loop on shutdown in a FastAPI application. We'll explore how to use the @app.on_event("shutdown") decorator to manage loop states and ensure your application exits gracefully. This approach is essential for applications that require persistent background processes or connections, such as WebSockets or periodic tasks.

Prerequisites

• Basic knowledge of Python and FastAPI.
• Python 3.10 or later installed on your machine.
• Familiarity with asynchronous programming concepts in Python.

Step 1: Setup Your FastAPI Project

First, ensure that you have FastAPI installed in your environment. If not, you can install it using pip:

pip install fastapi[all]

Next, create a new Python file, main.py, and set up a basic FastAPI application:

from fastapi import FastAPI
import asyncio

app = FastAPI()
running = True

@app.get("/")
async def index():
    while running:
        await asyncio.sleep(0.1)
    return {"message": "Loop stopped"}

This code sets up a basic FastAPI application with an endless loop running in the root path.

Step 2: Implement the Shutdown Event

To properly handle shutdowns, you need to implement the shutdown_event function that stops the loop by setting a global flag. Add the following code to your main.py:

@app.on_event("shutdown")
def shutdown_event():
    global running
    running = False
    print("Application is shutting down...")

This function will be called when the FastAPI application is shutting down, allowing you to change the state of the loop.

Step 3: Running and Testing Your Application

To run your FastAPI application, use the following command:

uvicorn main:app --reload

Visit http://127.0.0.1:8000/ in your browser to initiate the loop. When you stop the server (e.g., by pressing CTRL+C), the shutdown_event function will be triggered, stopping the loop gracefully.

Expected Output

When you visit the root URL, the server will continuously process the loop until shutdown. Upon shutdown, you should see "Application is shutting down..." printed in the console, indicating that the loop has stopped.

Common Errors/Troubleshooting

• Global Variable Not Updated: Ensure the running variable is declared as global in both the loop and the shutdown_event function.
• Shutdown Event Not Triggering: Verify that your application is using the correct event loop and that the @app.on_event("shutdown") decorator is correctly applied.
• Loop Continues After Shutdown: Confirm that the running flag is properly checked within the loop condition.

Frequently Asked Questions

Why does my loop not stop on shutdown?

Ensure that the shutdown event is properly set up and the global variable is correctly updated to stop the loop.

Can I stop multiple loops with a single shutdown event?

Yes, use the shutdown event to update multiple flags or send a signal to tasks to stop.

Is it safe to use global variables for loop control?

While global variables are convenient, consider using more structured approaches like context managers or state classes for complex applications.

Frequently Asked Questions

Why does my loop not stop on shutdown?

Ensure that the shutdown event is properly set up and the global variable is correctly updated to stop the loop.

Can I stop multiple loops with a single shutdown event?

Yes, use the shutdown event to update multiple flags or send a signal to tasks to stop.

Is it safe to use global variables for loop control?

While global variables are convenient, consider using more structured approaches like context managers or state classes for complex applications.