WebSocket Callbacks

New in Dash 4.2

Dash callbacks typically run over HTTP: inputs are sent to the server, the callback executes, and outputs are returned once complete. WebSocket callbacks use a persistent connection, allowing the server to push updates incrementally and query client state while the callback is still running.

WebSocket callbacks require a FastAPI or Quart backend. See Server Backends for setup instructions.

Use WebSocket callbacks when you need continuous updates or mid-execution interaction with the UI. Typical use cases include live data streams, progress indicators for long-running tasks, adaptive workflows that depend on current UI state, and real-time log or event display.

Enabling WebSocket Callbacks

To enable WebSocket callbacks for all the callbacks in an app, add websocket_callbacks=True to the Dash constructor:

app = Dash(backend="fastapi", websocket_callbacks=True)

Alternatively, you can enable them on specific callbacks with websocket=True. See Per-Callback WebSocket below.

Streaming Updates with set_props

Within a WebSocket callback, set_props sends updates immediately instead of waiting for the final return value. This allows multiple UI updates during a single execution.

The callback can stream intermediate values and still return a final state at completion.

Reading Props with get_prop

Access the WebSocket interface via ctx.websocket. Use get_prop to retrieve the current value of a component property from the browser.

This avoids declaring the property as State when the value may change during execution.

Per-Callback WebSocket

You can enable WebSocket transport on specific callbacks only:

Callbacks without websocket=True continue to use HTTP.

Persistent Callbacks

Standard callbacks run in response to user actions and show an “Updating…” indicator in the browser title while executing. This works well for discrete interactions, but some callbacks need to run continuously with no user-triggered input and no specific output (for example, pushing live data to a dashboard). A regular callback with no inputs would still fire once on load and display the loading state, which is misleading when the callback is meant to run indefinitely in the background.

The persistent=True flag solves this. A persistent callback:

• Starts automatically when the client connects and runs for the entire session.
• Doesn’t show a loading state. The browser title stays clean because there is no request/response cycle to track.
• Requires no Input or Output. Use set_props to push updates and ws.get_prop to read UI state.
• Stops when the client disconnects. ws.is_shutdown becomes True when the tab is closed or connectivity is lost.

@callback(persistent=True)
async def background_loop():
    ws = ctx.websocket
    while not ws.is_shutdown:
        set_props("live-display", {"children": get_latest_data()})
        await asyncio.sleep(0.5)

Use persistent callbacks when you want the server to push updates continuously without waiting for user interaction (typical use cases include live dashboards, simulations, and real-time data feeds).

Real-Time Data Streaming

WebSocket callbacks support long-running loops that both push updates and read UI state.

Common patterns:

• Handle asyncio.CancelledError to exit cleanly on disconnect.
• Use Patch() for incremental updates to stores.
• Call ws.get_prop to adapt behavior based on current UI state.

External WebSocket Integration

A callback can connect to an external WebSocket service and forward data to the client.

Typical flow:

1. Trigger callback from user input.
2. Inside the callback, open a connection to the external service with a WebSocket client library such as websockets.
3. Receive messages and stream them via set_props.
4. Use get_prop to adjust requests dynamically.
5. Handle disconnect via cancellation.

import asyncio
import websockets
from dash import callback, ctx, set_props, Input, Output

@callback(
    Output("status", "children"),
    Input("connect-btn", "n_clicks"),
    prevent_initial_call=True,
)
async def stream_from_service(n):
    ws = ctx.websocket
    if ws is None:
        return "WebSocket not available"

    set_props("status", {"children": "Connecting..."})

    try:
        async with websockets.connect("wss://example.com/feed") as upstream:
            set_props("status", {"children": "Connected"})

            while True:
                symbol = await ws.get_prop("symbol-select", "value")
                await upstream.send(symbol)

                message = await upstream.recv()
                set_props("live-output", {"children": message})

                await asyncio.sleep(1)

    except asyncio.CancelledError:
        pass

    return "Disconnected"

Dash does not provide an upstream client. Use an async-compatible library such as websockets.

Migrating from dcc.Interval

If you have an app that uses dcc.Interval for live updates, switching to a persistent WebSocket callback removes the polling overhead and gives you server-push instead of client-pull.

Before: polling with dcc.Interval

from dash import Dash, dcc, html, Input, Output, callback

app = Dash()

app.layout = html.Div([
    html.H4("Live Price"),
    html.Div(id="price-display"),
    dcc.Interval(id="poll", interval=1000, n_intervals=0),
])

@callback(Output("price-display", "children"), Input("poll", "n_intervals"))
def update_price(n):
    price = get_latest_price("AAPL")
    return f"AAPL: ${price}"

With this pattern, the browser sends a request every second regardless of whether new data is available. If get_latest_price takes longer than the interval, updates can stall or queue up.

After: server-push with a persistent callback

import asyncio
from dash import Dash, html, callback, ctx, set_props

app = Dash(backend="fastapi", websocket_callbacks=True)

app.layout = html.Div([
    html.H4("Live Price"),
    html.Div(id="price-display"),
])

@callback(persistent=True)
async def stream_price():
    ws = ctx.websocket
    while not ws.is_shutdown:
        price = get_latest_price("AAPL")
        set_props("price-display", {"children": f"AAPL: ${price}"})
        await asyncio.sleep(1)

The dcc.Interval component is gone. The server pushes updates when they’re ready, and the update frequency is controlled by asyncio.sleep rather than a fixed polling interval. If get_latest_price is slow, the next update simply waits until it finishes rather than queuing a backlog of requests.

Key differences:

dcc.Interval is still the best choice for apps that don’t need a FastAPI or Quart backend, or for infrequent updates (every 30 seconds or more) where polling overhead is negligible.

Examples

Game of Life

A persistent callback computes and streams successive states of a grid at a fixed frame rate.

Streaming into AG Grid

A persistent callback streams live price updates into a grid, updating rows in place.

Security

Origin Validation

WebSocket connections are restricted to the same origin by default. Add allowed origins explicitly when embedding:

app = Dash(
    backend="fastapi",
    websocket_callbacks=True,
    websocket_allowed_origins=["https://embedding-site.example.com"],
)

Secure Transport

When your app is served over HTTPS, WebSocket connections automatically upgrade to wss:// (the encrypted WebSocket protocol), so data in transit is protected by the same TLS certificate. No additional configuration is required.

Cross-site Scripting (XSS) Protection

Component prop updates sent via set_props are sanitized before rendering, so it is not possible for attackers to execute maliciously injected code in your app.

Input Validation

Always make sure that your app code validates all inputs used in database queries, shell commands, or external systems. Use parameterized queries.

Server-Initiated Disconnect

Use ws.close() inside a callback to forcibly disconnect a client (for example, when detecting suspicious input patterns, after a session has been revoked, or when enforcing rate limits). See Handling Disconnections for details.

Deployment

Plotly Cloud detects WebSocket callbacks automatically and configures the server for you. No additional setup is needed.

For self-managed deployments, WebSocket callbacks require a server that supports the WebSocket protocol. When deploying with uvicorn, install it with the standard extra to include a WebSocket implementation:

# requirements.txt
dash[fastapi]>=4.2
uvicorn[standard]

Without uvicorn[standard], the app will start and serve pages over HTTP, but WebSocket connections will silently fail. You will see "No supported WebSocket library detected" in the server logs.

A typical Procfile for Dash Enterprise:

web: uvicorn app:app.server --host 0.0.0.0 --port $PORT

Connection Limits and Scaling

WebSocket callback execution is bounded by a thread pool. Each active WebSocket callback (including each persistent callback) occupies one thread for the duration of its execution.

Thread pool sizing: Dash uses Python’s default ThreadPoolExecutor, which allocates min(32, cpu_count + 4) worker threads. On a 4-CPU server, that’s 8 threads. On a 16-CPU server, that’s 20 threads. The maximum is 32.

What this means for persistent callbacks: Since a persistent callback runs for the entire client session, it holds a thread the whole time. With the default pool size, the number of concurrent users with active persistent callbacks is limited to the thread pool size. Additional connections are queued and will start executing when a thread becomes available.

Memory per connection: Each active WebSocket callback allocates a queue for outgoing messages, a dictionary for pending property requests, and a shutdown event. The dominant cost is the thread itself, which typically uses around 8 MB of stack space. Expect roughly 8-10 MB of memory per concurrent persistent callback.

Scaling strategies:
- For higher concurrency, deploy multiple workers behind a load balancer. Each worker has its own thread pool.
- Keep persistent callback loops efficient. A callback that sleeps most of the time still holds its thread.
- Use per-callback WebSocket (websocket=True) for short-lived operations instead of persistent callbacks where possible, since these release their thread when the callback returns.

Handling Disconnections

Disconnections can be initiated by the client (tab closed, navigation, lost connectivity) or by the server (calling ws.close()). In both cases, your callback needs to detect the disconnect and clean up.

For persistent callbacks, check ws.is_shutdown in their loop condition. When the connection closes, ws.is_shutdown becomes True and the loop exits:

@callback(persistent=True)
async def background_loop():
    ws = ctx.websocket
    while not ws.is_shutdown:
        set_props("output", {"children": get_data()})
        await asyncio.sleep(1)
    # Connection closed -- clean up resources here

Event-triggered callbacks (those with Input) receive an asyncio.CancelledError when the connection closes. Catch it to run cleanup logic:

@callback(Output("status", "children"), Input("btn", "n_clicks"),
          prevent_initial_call=True)
async def long_task(n):
    try:
        while True:
            set_props("progress", {"children": "Working..."})
            await asyncio.sleep(1)
    except asyncio.CancelledError:
        # Client disconnected -- clean up resources here
        pass
    return "Done"

Server-initiated disconnect uses ws.close() to end the connection programmatically. The callback can continue running after calling close() to perform cleanup, but no further updates will reach the client:

if suspicious_activity:
    await ws.close(code=4001, reason="Policy violation")

Constructor Parameters

API Reference

ctx.websocket returns the WebSocket interface when running over WebSocket, otherwise None.

ws.is_shutdown is True when the WebSocket connection has closed (tab closed, navigation, or lost connectivity). Check this in long-running loops to exit cleanly.

ws.close(code=1000, reason="Connection closed") closes the WebSocket connection from the server side. Use this to forcibly disconnect a client, for example on suspicious activity, session revocation, or policy violation.

ws.get_prop(component_id, prop_name, timeout=30.0) asynchronously retrieves the current value of a component property from the client.

Use set_props to send updates. In WebSocket callbacks, updates are streamed immediately.