FastAPI SocketIO

0.0.10 verified Fri May 01 auth: no python maintenance

A library to easily integrate Socket.IO with FastAPI applications. Current version is 0.0.10, last updated in 2022. Release cadence is low, with infrequent updates. It wraps the python-socketio library for ASGI mode.

pip install fastapi-socketio

Common errors

error ImportError: cannot import name 'SocketManager' from 'fastapi_socketio' ↓

cause Incorrect import path; used old pattern or installed wrong package.

fix

Use: from fastapi_socketio import SocketManager

error RuntimeError: You cannot use SocketManager without an app ↓

cause SocketManager initialized without passing the FastAPI app object.

fix

Pass the app: SocketManager(app=app)

error TypeError: __init__() got an unexpected keyword argument 'cors_allowed_origins' ↓

cause CORS configuration is not passed to SocketManager directly; it must be set at the ASGI level.

fix

Use SocketManager(app=app, cors_allowed_origins=[]) is invalid. Instead configure CORS via FastAPI middleware.

Warnings

gotcha SocketManager is not an ASGI application itself; the library does not support multiple socket.io endpoints out of the box. ↓

fix Use one SocketManager per app. For multiple endpoints, consider custom handling.

gotcha The `async_mode` argument defaults to 'asgi'. Setting it to 'sanic' or 'aiohttp' may break ASGI compatibility. ↓

fix Leave `async_mode` unset or set to 'asgi' for typical FastAPI usage.

deprecated The library is no longer actively maintained; last release in 2022. May have compatibility issues with newer FastAPI or python-socketio versions. ↓

fix Consider using python-socketio's built-in ASGIApp directly (see python-socketio docs).

Imports

SocketManager

from fastapi_socketio import SocketManager

Quickstart

Basic setup with FastAPI and SocketManager handling connect, disconnect, and message events.

from fastapi import FastAPI
from fastapi_socketio import SocketManager

app = FastAPI()
socket_manager = SocketManager(app=app)

@app.get("/")
def read_root():
    return {"Hello": "World"}

@socket_manager.on('connect')
async def handle_connect(sid, environ):
    print(f"Client connected: {sid}")

@socket_manager.on('disconnect')
async def handle_disconnect(sid):
    print(f"Client disconnected: {sid}")

@socket_manager.on('message')
async def handle_message(sid, data):
    await socket_manager.emit('response', {'data': 'Received'}, room=sid)

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)