Getting Started

What is Socket.IO?

Socket.IO is a transport protocol that enables real-time bidirectional event-based communication between clients (typically, though not always, web browsers) and a server. The official implementations of the client and server components are written in JavaScript. This package provides Python implementations of both, each with standard and asyncio variants.

Version compatibility

The Socket.IO protocol has been through a number of revisions, and some of these introduced backward incompatible changes, which means that the client and the server must use compatible versions for everything to work.

If you are using the Python client and server, the easiest way to ensure compatibility is to use the same version of this package for the client and the server. If you are using this package with a different client or server, then you must ensure the versions are compatible.

The version compatibility chart below maps versions of this package to versions of the JavaScript reference implementation and the versions of the Socket.IO and Engine.IO protocols.

JavaScript Socket.IO version	Socket.IO protocol revision	Engine.IO protocol revision	python-socketio version	python-engineio version
0.9.x	1, 2	1, 2	Not supported	Not supported
1.x and 2.x	3, 4	3	4.x	3.x
3.x and 4.x	5	4	5.x	4.x

Client Examples

The example that follows shows a simple Python client:

import socketio

sio = socketio.Client()

@sio.event
def connect():
    print('connection established')

@sio.event
def my_message(data):
    print('message received with ', data)
    sio.emit('my response', {'response': 'my response'})

@sio.event
def disconnect():
    print('disconnected from server')

sio.connect('http://localhost:5000')
sio.wait()

Below is a similar client, coded for asyncio (Python 3.5+ only):

import asyncio
import socketio

sio = socketio.AsyncClient()

@sio.event
async def connect():
    print('connection established')

@sio.event
async def my_message(data):
    print('message received with ', data)
    await sio.emit('my response', {'response': 'my response'})

@sio.event
async def disconnect():
    print('disconnected from server')

async def main():
    await sio.connect('http://localhost:5000')
    await sio.wait()

if __name__ == '__main__':
    asyncio.run(main())

Client Features

• Can connect to other Socket.IO servers that are compatible with the JavaScript Socket.IO 1.x and 2.x releases. Work to support release 3.x is in progress.

• Compatible with Python 3.6+.

• Two versions of the client, one for standard Python and another for asyncio.

• Uses an event-based architecture implemented with decorators that hides the details of the protocol.

• Implements HTTP long-polling and WebSocket transports.

• Automatically reconnects to the server if the connection is dropped.

Server Examples

The following application is a basic server example that uses the Eventlet asynchronous server:

import eventlet
import socketio

sio = socketio.Server()
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.event
def disconnect(sid):
    print('disconnect ', sid)

if __name__ == '__main__':
    eventlet.wsgi.server(eventlet.listen(('', 5000)), app)

Below is a similar application, coded for asyncio (Python 3.5+ only) and the Uvicorn web server:

from aiohttp import web
import socketio

sio = socketio.AsyncServer()
app = web.Application()
sio.attach(app)

async def index(request):
    """Serve the client-side application."""
    with open('index.html') as f:
        return web.Response(text=f.read(), content_type='text/html')

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

@sio.event
async def chat_message(sid, data):
    print("message ", data)

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

app.router.add_static('/static', 'static')
app.router.add_get('/', index)

if __name__ == '__main__':
    web.run_app(app)

Server Features

• Can connect to servers running other Socket.IO clients that are compatible with the JavaScript client versions 1.x and 2.x. Work to support the 3.x release is in progress.

• Compatible with Python 3.6+.

• Two versions of the server, one for standard Python and another for asyncio.

• Supports large number of clients even on modest hardware due to being asynchronous.

• Can be hosted on any WSGI or ASGI web server including Gunicorn, Uvicorn, eventlet and gevent.

• Can be integrated with WSGI applications written in frameworks such as Flask, Django, etc.

• Can be integrated with aiohttp, sanic and tornado asyncio applications.

• Broadcasting of messages to all connected clients, or to subsets of them assigned to “rooms”.

• Optional support for multiple servers, connected through a messaging queue such as Redis or RabbitMQ.

• Send messages to clients from external processes, such as Celery workers or auxiliary scripts.

• Event-based architecture implemented with decorators that hides the details of the protocol.

• Support for HTTP long-polling and WebSocket transports.

• Support for XHR2 and XHR browsers.

• Support for text and binary messages.

• Support for gzip and deflate HTTP compression.

• Configurable CORS responses, to avoid cross-origin problems with browsers.