{"library":"python-socketio","title":"Python Socket.IO","description":"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.","status":"active","version":"5.16.1","language":"en","source_language":"en","source_url":"https://github.com/miguelgrinberg/python-socketio","tags":["websocket","realtime","async","socket.io","networking"],"install":[{"cmd":"pip install python-socketio","lang":"bash","label":"Install server"},{"cmd":"pip install \"python-socketio[client]\"","lang":"bash","label":"Install standard client"},{"cmd":"pip install \"python-socketio[asyncio_client]\"","lang":"bash","label":"Install asyncio client"}],"dependencies":[{"reason":"Core dependency for the underlying Engine.IO transport protocol.","package":"python-engineio"},{"reason":"Recommended ASGI web server for `socketio.AsyncServer` deployments.","package":"uvicorn","optional":true},{"reason":"Common WSGI/ASGI web server. Can be used with `eventlet`, `gevent`, or `threading` workers.","package":"gunicorn","optional":true},{"reason":"Asynchronous framework for WSGI servers; less actively maintained than `gevent` or `asyncio`.","package":"eventlet","optional":true},{"reason":"Asynchronous framework for WSGI servers, often used with `gunicorn`.","package":"gevent","optional":true},{"reason":"Required for `socketio.RedisManager` for message queue support across multiple processes or servers (standard).","package":"redis","optional":true},{"reason":"Required for `socketio.AsyncRedisManager` for message queue support (asyncio).","package":"aioredis","optional":true},{"reason":"Required for `socketio.KombuManager` for message queue support (e.g., RabbitMQ).","package":"kombu","optional":true},{"reason":"Required for `socketio.KafkaManager` for Kafka message queue support.","package":"kafka-python","optional":true}],"imports":[{"symbol":"Server","correct":"import socketio\nsio = socketio.Server()"},{"symbol":"AsyncServer","correct":"import socketio\nsio = socketio.AsyncServer()"},{"symbol":"Client","correct":"import socketio\nsio = socketio.Client()"},{"symbol":"AsyncClient","correct":"import socketio\nsio = socketio.AsyncClient()"},{"symbol":"WSGIApp","correct":"import socketio\napp = socketio.WSGIApp(sio)"},{"symbol":"ASGIApp","correct":"import socketio\napp = socketio.ASGIApp(sio)"}],"quickstart":{"code":"import socketio\nimport eventlet\n\nsio = socketio.Server(cors_allowed_origins=\"*\")\napp = socketio.WSGIApp(sio, static_files={\n '/': {'content_type': 'text/html', 'filename': 'index.html'}\n})\n\n@sio.event\ndef connect(sid, environ):\n print('connect ', sid)\n\n@sio.event\ndef my_message(sid, data):\n print('message ', data)\n sio.emit('my response', {'data': data}, room=sid)\n\n@sio.event\ndef disconnect(sid):\n print('disconnect ', sid)\n\nif __name__ == '__main__':\n # index.html for testing\n with open('index.html', 'w') as f:\n f.write('''\n \n \n \n Socket.IO Test\n \n \n \n Socket.IO Test
\n \n \n \n ''')\n print(\"Starting server on http://localhost:5000\")\n eventlet.wsgi.server(eventlet.listen(('', 5000)), app)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, especially migrating from python-socketio 4.x to 5.x"},{"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']`).","message":"Missing or incorrect `cors_allowed_origins` can cause connection refusal errors for browser-based clients due to Cross-Origin Resource Sharing (CORS) policies.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"All versions"},{"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.","message":"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`.","severity":"breaking","affected_versions":"python-socketio >= 5.0"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}