Flask-SocketIO

Warnings

• breaking Flask-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`).
• gotcha For 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`).
• gotcha Asynchronous 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.
• breaking When 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`).
• gotcha Modifications 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.
• gotcha Blocking 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)`.

Install

• pip install Flask-SocketIO Basic Installation
• pip install Flask-SocketIO[eventlet] With Eventlet (Async Server)
• pip install Flask-SocketIO[gevent] With Gevent (Async Server, Recommended)
• pip install Flask-SocketIO redis With Redis Message Queue (for Scaling)

Imports

• SocketIO

  from flask_socketio import SocketIO

• send

  from flask_socketio import send

  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

Quickstart

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)