How do you handle WebSockets in FastAPI?

Question

Accepted Answer

FastAPI supports **WebSockets** for real-time, bidirectional communication (chat, live updates, notifications) via the `@app.websocket` decorator. Unlike HTTP's request-response, a WebSocket connection stays open, letting the server and client send messages freely.

## A basic WebSocket endpoint

```python
from fastapi import WebSocket, WebSocketDisconnect

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()                  # accept the connection
    try:
        while True:
            data = await websocket.receive_text()    # receive a message from the client
            await websocket.send_text(f"Echo: {data}")  # send a message back
    except WebSocketDisconnect:
        print("client disconnected")           # handle disconnection (cleanup)
```

The pattern: `accept()` the connection, then loop — `receive_text()`/`receive_json()` reads messages, `send_text()`/`send_json()` sends them. A `WebSocketDisconnect` exception signals the client left (where you clean up).

## Broadcasting to multiple clients (e.g. chat)

```python
class ConnectionManager:
    def __init__(self): self.active: list[WebSocket] = []
    async def connect(self, ws): await ws.accept(); self.active.append(ws)
    def disconnect(self, ws): self.active.remove(ws)
    async def broadcast(self, msg):
        for conn in self.active:
            await conn.send_text(msg)          # send to ALL connected clients

manager = ConnectionManager()

@app.websocket("/chat")
async def chat(ws: WebSocket):
    await manager.connect(ws)
    try:
        while True:
            msg = await ws.receive_text()
            await manager.broadcast(msg)        # everyone gets the message
    except WebSocketDisconnect:
        manager.disconnect(ws)                  # remove on disconnect
```

Managing a list of active connections lets you **broadcast** to all clients — the basis of chat and live-update features.

## Scaling caveat

```text
⚠️ WebSocket connections are STATEFUL and live on ONE server instance.
To scale across multiple instances, use a Redis Pub/Sub (or similar) backplane so
messages/broadcasts reach clients connected to OTHER instances.
(Like sessions, don't keep connection state only in one process when scaling horizontally.)
```

## Why it matters

WebSockets enable **real-time, bidirectional** features — chat, live notifications, presence, collaborative editing, live dashboards — that HTTP's request-response model can't provide (the server can push to clients, not just respond).

Understanding FastAPI's WebSocket support is valuable for building modern interactive applications: the `@app.websocket` decorator with the accept/receive/send loop covers basic real-time communication, and managing active connections enables **broadcasting** (the core of multi-user features like chat).

FastAPI's async foundation suits WebSockets well.

Critically important is the **scaling caveat**: WebSocket connections are stateful and tied to a single server instance, so scaling across multiple instances requires a **Redis Pub/Sub backplane** to relay messages between instances — a common pitfall, since (like sessions) connection state can't live in one process's memory when running multiple instances.

Knowing the basic WebSocket pattern, broadcasting, disconnect handling, and the scaling consideration is important senior-level knowledge for building the real-time, interactive experiences increasingly expected in modern applications.