Python Socket.IO

5.16.1 · active · verified Mon Apr 06

python-socketio is a comprehensive Python implementation of the Socket.IO real-time communication protocol, offering both server and client functionalities. It enables low-latency, bidirectional, and event-based communication between clients (often web browsers) and a Python server. The library is actively maintained with frequent releases, providing compatibility with various asynchronous frameworks and web servers.

Warnings

breaking Protocol compatibility is critical: python-socketio v5.x is compatible with JavaScript Socket.IO 3.x and 4.x. Mixing incompatible versions will lead to connection errors or unexpected behavior.
Fix: Consult the version compatibility chart in the official documentation (e.g., PyPI or GitHub README) and ensure both client and server are using compatible protocol versions. Upgrade client-side libraries (e.g., JavaScript `socket.io-client`) if upgrading the Python server.
gotcha Missing or incorrect `cors_allowed_origins` can cause connection refusal errors for browser-based clients due to Cross-Origin Resource Sharing (CORS) policies.
Fix: Explicitly set `cors_allowed_origins` when initializing `socketio.Server` or `socketio.AsyncServer`. For development, `cors_allowed_origins="*"` is common, but for production, specify exact origins (e.g., `['http://example.com', 'https://www.example.com']`).
gotcha Using `Gunicorn` with multiple worker processes for `python-socketio` requires sticky sessions (load balancer must route a client to the same worker) and forcing WebSocket-only transport. Long-polling is incompatible with Gunicorn's default load balancing across workers.
Fix: If deploying with multiple Gunicorn workers, configure your load balancer for sticky sessions (e.g., Nginx `ip_hash` directive) and initialize the Socket.IO server with `transports=['websocket']`. Also, a message queue is required for inter-worker communication (e.g., broadcasting).
deprecated The `eventlet` asynchronous framework, while supported, is no longer actively maintained. Using `gevent` or `asyncio` is generally recommended for new projects for better long-term support and performance.
Fix: For new projects, consider `gevent` or `asyncio` (`uvicorn` with `socketio.ASGIApp`) for concurrency. If using `eventlet` or `gevent` with other blocking libraries (like database drivers), ensure proper monkey patching.
breaking In Socket.IO v5 protocol (python-socketio 5.x), the default namespace ('/') is not automatically connected. Each namespace connection, including the default, now has its own unique session ID (`sid`), distinct from the Engine.IO `sid`.
Fix: Ensure clients explicitly connect to namespaces if relying on them. When handling events, be aware that the `sid` parameter for event handlers will be specific to the namespace. If upgrading from older versions, update client-side code to explicitly manage namespace connections.

Install

pip install python-socketio Install server
pip install "python-socketio[client]" Install standard client
pip install "python-socketio[asyncio_client]" Install asyncio client

Imports

Server
```
import socketio
sio = socketio.Server()
```

AsyncServer

import socketio
sio = socketio.AsyncServer()

Client
```
import socketio
sio = socketio.Client()
```

AsyncClient

import socketio
sio = socketio.AsyncClient()

WSGIApp

import socketio
app = socketio.WSGIApp(sio)

ASGIApp

import socketio
app = socketio.ASGIApp(sio)

Quickstart

This quickstart demonstrates a basic Socket.IO server using `eventlet` and a simple HTML client. The server defines handlers for `connect`, `my_message`, and `disconnect` events. The client connects, sends a message, and receives a response. An `index.html` file is created on the fly for easy testing. Remember to `pip install eventlet` for this example to run.

import socketio
import eventlet

sio = socketio.Server(cors_allowed_origins="*")
app = socketio.WSGIApp(sio, static_files={
    '/': {'content_type': 'text/html', 'filename': 'index.html'}
})

@sio.event
def connect(sid, environ):
    print('connect ', sid)

@sio.event
def my_message(sid, data):
    print('message ', data)
    sio.emit('my response', {'data': data}, room=sid)

@sio.event
def disconnect(sid):
    print('disconnect ', sid)

if __name__ == '__main__':
    # index.html for testing
    with open('index.html', 'w') as f:
        f.write('''
            <!DOCTYPE html>
            <html>
            <head>
                <title>Socket.IO Test</title>
                <script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/4.0.1/socket.io.js"></script>
            </head>
            <body>
                <h1>Socket.IO Test</h1>
                <script type="text/javascript">
                    var socket = io();
                    socket.on('connect', function() {
                        console.log('Connected!');
                        socket.emit('my_message', 'Hello from browser!');
                    });
                    socket.on('my response', function(data) {
                        console.log('Received:', data);
                    });
                    socket.on('disconnect', function() {
                        console.log('Disconnected!');
                    });
                </script>
            </body>
            </html>
        ''')
    print("Starting server on http://localhost:5000")
    eventlet.wsgi.server(eventlet.listen(('', 5000)), app)

view raw JSON →