Install & Compatibility
Where this runs
tested against v5.16.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 0.482s · 23.8MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 2.5s · import 0.440s · 24MB
26MB installed
● package 26MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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)
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)
Debug
Known issues
breakingProtocol 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.fixConsult 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.
affects: All versions, especially migrating from python-socketio 4.x to 5.x
gotchaMissing or incorrect `cors_allowed_origins` can cause connection refusal errors for browser-based clients due to Cross-Origin Resource Sharing (CORS) policies.fixExplicitly 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']`).
affects: All versions
gotchaUsing `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.fixIf 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).
affects: All versions
deprecatedThe `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.fixFor 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.
affects: All versions
breakingIn 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`.fixEnsure 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.
affects: python-socketio >= 5.0
gotchaIf your application is configured to use `eventlet` (e.g., `import eventlet`), ensure it is explicitly installed. `python-socketio` supports multiple asynchronous backends, and specific backends like `eventlet` are not installed by default as core dependencies.fixExplicitly install the required asynchronous framework (e.g., `pip install eventlet`). For new projects, consider the recommended alternatives like `gevent` or `asyncio` (as advised in Warning 3) and install them accordingly.
affects: All versions
Upgrade
Version history
5.16.4latest on PyPI · released Aug 6, 2026
Audit
Dependencies
python-engineiorequiredCore dependency for the underlying Engine.IO transport protocol.
uvicornoptionalRecommended ASGI web server for `socketio.AsyncServer` deployments.
gunicornoptionalCommon WSGI/ASGI web server. Can be used with `eventlet`, `gevent`, or `threading` workers.
eventletoptionalAsynchronous framework for WSGI servers; less actively maintained than `gevent` or `asyncio`.
geventoptionalAsynchronous framework for WSGI servers, often used with `gunicorn`.
redisoptionalRequired for `socketio.RedisManager` for message queue support across multiple processes or servers (standard).
aioredisoptionalRequired for `socketio.AsyncRedisManager` for message queue support (asyncio).
kombuoptionalRequired for `socketio.KombuManager` for message queue support (e.g., RabbitMQ).
kafka-pythonoptionalRequired for `socketio.KafkaManager` for Kafka message queue support.