Registry / web-framework / flask-socketio

flask-socketio

library5.6.1pypypi✓ verified 28d ago

Flask-SocketIO is a Flask extension that enables real-time bidirectional communication between clients and servers using the Socket.IO protocol. It provides features like event-based communication, rooms for grouping clients, namespaces for organization, and automatic reconnection. The library is actively maintained, with frequent releases, and its current version is 5.6.1.

web-framework http-networking communication

pip install Flask-SocketIO

github ↗package ↗

INSTALL

IMPORT

SIG · FLASK-SOCKETIO

flask-socketio

web-frameworkpythonv5.6.1

Install

2.8s avg

Import

778ms

Disk

29MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.6.1 · 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

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.824s · 29.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.8s · import 0.732s · 30MB

29MB installed

● package 29MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SocketIO

✓ from flask_socketio import SocketIO

send

✓ from flask_socketio import send

✗ socketio.send() within an event handler context without explicit import

The context-aware `send()` and `emit()` (for use inside event handlers) are typically imported directly. The `socketio.send()` and `socketio.emit()` methods are for server-originated messages outside a request context.

emit

✓ from flask_socketio import emit

This quickstart demonstrates a basic Flask-SocketIO application. It initializes a Flask app, wraps it with `SocketIO`, and defines event handlers for `my event` and `message`. The `my event` handler echoes data back to the sender, while the `message` handler broadcasts to all connected clients. Crucially, `socketio.run(app)` is used instead of `app.run()` to start the server, enabling WebSocket support. For production, asynchronous workers like eventlet or gevent are recommended.

from flask import Flask, render_template from flask_socketio import SocketIO, emit app = Flask(__name__) app.config['SECRET_KEY'] = 'my_secret_key' socketio = SocketIO(app) @app.route('/') def index(): return render_template('index.html') @socketio.on('my event') def handle_my_custom_event(json): print('received json: ' + str(json)) # Logs to server console emit('my response', json) # Sends a response back to the client that sent it @socketio.on('message') def handle_message(message): print('received message: ' + message) emit('my response', {'data': message}, broadcast=True) # Broadcasts to all connected clients if __name__ == '__main__': # For development, socketio.run() replaces app.run() # For production, install eventlet or gevent for async workers socketio.run(app, debug=True)

Debug

Known issues

breakingFlask-SocketIO 5.x adopted backwards-incompatible changes in the Socket.IO protocol (Socket.IO v3+). This requires the client-side Socket.IO JavaScript library to also be upgraded to a compatible version (e.g., 3.x or 4.x). Mismatched protocol versions will result in connection failures and '400' errors.

fix

Ensure your client-side Socket.IO library (e.g., JavaScript client) is compatible with Socket.IO protocol v3 or later. Upgrade `socket.io-client` in your frontend project (e.g., `npm install socket.io-client@^4.0.0`).

affects: 5.0.0 and later

gotchaFor production deployments, `socketio.run(app)` should always be used to start the server instead of `app.run()`. `socketio.run()` ensures that an appropriate asynchronous web server (like Eventlet or Gevent, if installed) is used, which is necessary for proper WebSocket functionality and performance. Using `app.run()` will default to Flask's built-in development server, which lacks robust WebSocket support and is not suitable for production.

fix

Replace `app.run()` with `socketio.run(app)`. Additionally, for production, install an asynchronous worker (e.g., `pip install gevent`).

affects: All versions

gotchaAsynchronous workers (like `gevent` or `eventlet`) are crucial for performance and proper WebSocket handling in production environments. Without them, Flask-SocketIO defaults to Python's threading, which can lead to performance bottlenecks and unresponsiveness under high load. `gevent` is generally preferred over `eventlet` as `eventlet` is in maintenance mode.

fix

Install either `gevent` (`pip install gevent`) or `eventlet` (`pip install eventlet`). `gevent` is recommended. If using a message queue, 'monkey patching' of the standard library might be required by calling `eventlet.monkey_patch()` or `from gevent import monkey; monkey.patch_all()` at the very top of your main script.

affects: All versions

breakingWhen running multiple Flask-SocketIO server instances behind a load balancer (for scaling), a message queue (such as Redis or RabbitMQ) is mandatory for coordinating operations like broadcasting and rooms. Without a message queue, events will only be delivered to clients connected to the specific server instance that emitted the event. Additionally, the load balancer *must* be configured for 'sticky sessions' to ensure a client's requests are always routed to the same worker.

fix

Configure a message queue (e.g., `socketio = SocketIO(app, message_queue='redis://localhost:6379')`) and ensure your load balancer uses 'sticky sessions' (e.g., `ip_hash` in Nginx). Install the corresponding message queue package (e.g., `pip install redis`).

affects: All versions

gotchaModifications to the Flask `session` object within SocketIO event handlers create a 'fork' of the session that is independent of the session seen by regular HTTP routes. Changes made in a SocketIO handler will persist for subsequent SocketIO handlers on the same connection but will *not* be visible to Flask HTTP route handlers (and vice-versa). This is due to how sessions are saved, requiring HTTP request/response cycles that don't exist in a SocketIO connection.

fix

Be aware of this session isolation. If shared session state between HTTP and SocketIO is critical, consider server-side session extensions (e.g., Flask-Session, Flask-KVSession) and initialize `SocketIO(app, manage_session=False)` to allow Flask's session management to be used.

affects: All versions

gotchaBlocking operations (e.g., long database queries, heavy computations, network calls) within SocketIO event handlers will block the entire server process when using an asynchronous framework like Gevent or Eventlet, leading to severe performance issues and unresponsiveness.

fix

For any potentially blocking operations, offload them to a background task or thread using `socketio.start_background_task()` or a dedicated task queue (e.g., Celery). For example: `socketio.start_background_task(my_long_running_function, arg1, arg2)`.

affects: All versions

Errors

Common errors & fixes

The client is using an unsupported version of the Socket.IO or Engine.IO protocols

This error occurs due to a version mismatch between the client-side Socket.IO JavaScript library and the server-side Python `Flask-SocketIO`, `python-socketio`, or `python-engineio` packages.

fix

Ensure that the versions of your client-side Socket.IO library (e.g., from a CDN or npm) and your server-side Python packages (`Flask-SocketIO`, `python-socketio`, `python-engineio`) are compatible. Consult the Flask-SocketIO documentation for recommended compatible versions.

socketio.run(app) does not start the server or `app.run()` is used instead of `socketio.run()`

Developers often mistakenly use `app.run()` to start their Flask application, which will not enable WebSocket support provided by Flask-SocketIO. Alternatively, `socketio.run(app)` might not start correctly if required asynchronous packages like `eventlet` or `gevent` are missing or misconfigured.

fix

Always use `socketio.run(app)` to start your Flask-SocketIO server. For production environments, ensure you have installed an asynchronous web server like `eventlet` (`pip install eventlet`) or `gevent` (`pip install gevent`).

SocketIO events defined with `@socketio.on` are not triggered on the server

This typically happens when the client is trying to connect to a different Socket.IO namespace or path than the server expects, often due to misinterpreting Flask blueprint URLs as Socket.IO paths, or incorrect namespace configuration on either the client or server.

fix

Verify that your client-side connection URL correctly specifies the Socket.IO namespace (e.g., `io('/my_namespace')`) if your server-side event handlers are defined for a specific namespace. Do not confuse Flask blueprint `url_prefix` with Socket.IO namespaces, as they operate independently.

ModuleNotFoundError: No module named 'flask_socketio'

The `Flask-SocketIO` library is not installed in the Python environment where the application is being run, or there is a typo in the import statement.

fix

Install the `Flask-SocketIO` package using pip: `pip install Flask-SocketIO`. Also, ensure that the import statement is `from flask_socketio import SocketIO` and not `from Flask_SocketIO import SocketIO` or similar.

Upgrade

Version history

5.6.1latest on PyPI · released Feb 21, 2026

Audit

Dependencies

eventletoptionalAsynchronous web server for production deployments, providing WebSocket support. Less actively maintained than gevent.

geventoptionalRecommended asynchronous web server for production deployments, providing WebSocket support and better performance than eventlet.

redisoptionalRequired for using Redis as a message queue for inter-process communication when deploying multiple workers or emitting from external processes.

kombuoptionalRequired for using RabbitMQ or other Kombu-supported message queues for inter-process communication when deploying multiple workers or emitting from external processes.

kafka-pythonoptionalRequired for using Kafka as a message queue for inter-process communication when deploying multiple workers or emitting from external processes.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/miguelgrinberg/flask-socketio ↗

packagehttps://pypi.org/project/flask-socketio/ ↗