Flask-SocketIO: Socket.IO integration for Flask applications

What Flask-SocketIO actually adds to a Flask app

Flask ships with request and response cycles. A browser opens a connection, asks for something, gets an answer, and the connection is done. Socket.IO is a different shape: the client and server stay connected, and either side can push a named event at any moment. Flask-SocketIO is the adapter that lets a Flask application speak that protocol without running a second service.

The package description in pyproject.toml is one line: "Socket.IO integration for Flask applications." That is the whole scope. It is not a general WebSocket library, and it does not replace Flask. It wires the python-socketio server into Flask's application object so that a function decorated with @socketio.event receives events emitted by a browser client.

The intended audience is a Python developer who already has a Flask app and now needs server-pushed updates: chat messages, notifications, live counters, collaborative state. If your app only ever answers HTTP requests, this package adds a dependency and a second network protocol for no gain.

How the event loop and the Flask app object fit together

The mechanism visible in the README example is a SocketIO object constructed from the Flask app. That object holds the Socket.IO server and registers the app as the source of configuration and request context. Handlers are plain Python functions registered by decorator, and inside a handler you call emit to send an event back.

The critical detail is how the app is served. The README example ends with socketio.run(app) rather than app.run(). The Socket.IO server owns the listening socket in that case, and Flask is invoked underneath it. Start the app with the Flask CLI or a plain WSGI server and the HTTP routes may work while the Socket.IO endpoint does not, because nothing is listening for the Socket.IO handshake.

Event names are strings, and the decorator can take one explicitly. The README shows the shorthand form where the function name becomes the event name, so a client emitting 'my_event' reaches the my_event function. The handler in the example replies with emit('my response', {'data': 'got it!'}), which is an event named with a space in it. Socket.IO does not restrict event names to identifiers, so this works, but it means the client and server must agree on the exact string.

For anything beyond a single process, the README is silent. The documentation site linked from the README is where message queues and multiple workers are described, and that is the material to read before assuming horizontal scaling works out of the box.

Installing Flask-SocketIO and running a first event

Installation is a single pip command. The README gives it directly:

pip install flask-socketio

The package metadata requires Python 3.8 or newer and pulls in Flask 2.1.0 or newer plus python-socketio 5.12.0 or newer. Those two version floors are the ones to check when an existing environment refuses to resolve.

A minimal working app, taken from the README example, looks like this. Save it as app.py:

from flask import Flask, render_template
from flask_socketio import SocketIO, emit

app = Flask(__name__)
app.config['SECRET_KEY'] = 'secret!'
socketio = SocketIO(app)

@app.route('/')
def index():
    return render_template('index.html')

@socketio.event
def my_event(message):
    emit('my response', {'data': 'got it!'})

if __name__ == '__main__':
    socketio.run(app)

The SECRET_KEY assignment matters because Flask uses it to sign session data, and Socket.IO connections carry session context. The README does not explain why the key is set in the example, but leaving it out is a common source of confusing failures later.

Run it with python app.py. The README does not state a default port for socketio.run, so treat the port as whatever your Flask configuration resolves to rather than assuming a value. On the browser side you need a Socket.IO client that connects to the same origin and emits 'my_event'. What you should see is the server calling the handler and the client receiving a 'my response' event carrying {'data': 'got it!'}.

If you prefer to see a fuller setup, the repository ships an example directory with app.py, app_namespace.py, sessions.py and a templates folder. Those files are the closest thing to a reference implementation in the repository itself.

The deployment constraint the README does not spell out

The README example is a development shape. socketio.run(app) starts a server suitable for local work, and the README says nothing about production deployment, worker counts or message queues.

This is the limitation that catches people. A Socket.IO connection is stateful: a given client is attached to a specific server process. Run two workers behind a load balancer without a shared message queue and a client can be connected to worker A while an event is emitted from worker B, so the message never arrives. The symptom is intermittent, which makes it worse than a clean failure.

The optional dev dependencies in pyproject.toml include redis, and the documentation linked from the README covers message queues. That is the direction to look, but the README itself does not document any of it. If your plan is multiple processes or multiple hosts, budget time for reading the docs site before you commit.

The second constraint is protocol. Socket.IO is not raw WebSocket. A client that opens a plain WebSocket connection to your endpoint will not complete the Socket.IO handshake. If the other end is not a Socket.IO client, this package is the wrong layer.

Flask-SocketIO compared with raw WebSockets and with python-socketio alone

The alternative people reach for first is a raw WebSocket implementation, typically through a library that hooks into the WSGI or ASGI stack. The difference is in what you get for free. Raw WebSockets give you a frame transport and nothing else: no event names, no automatic reconnection, no fallback transport when a WebSocket upgrade is blocked by a proxy. Socket.IO defines an event protocol on top of the transport and handles reconnection and transport negotiation on the client side. If your requirement is a binary stream with no message semantics, raw WebSockets are simpler and remove a dependency.

The other alternative is python-socketio on its own. Flask-SocketIO depends on python-socketio, and pyproject.toml pins it at 5.12.0 or newer. Using python-socketio directly means you define the server without Flask: no app object, no Flask configuration, no Flask session integration. That is a reasonable choice for a standalone realtime service that has no web framework around it. The reason to pick Flask-SocketIO instead is that your HTTP routes, templates, configuration and session handling already live in Flask, and splitting the realtime layer into a separate process would mean duplicating that context.

Maintenance, releases and what the MIT licence means here

The repository is not archived, and the last push was on 2026-08-29. Recent releases listed are v5.6.1 on 2026-02-21, v5.6.0 on 2025-12-25 and v5.5.1 on 2025-01-06. The version in pyproject.toml is 5.6.2.dev0, which indicates work toward the next release rather than a frozen tree.

Upgrade cost is bounded by the dependency floors. The package requires Flask 2.1.0 or newer and python-socketio 5.12.0 or newer, so an upgrade of Flask-SocketIO can force an upgrade of those two as well. The CHANGES.md file at the repository root is the place to read before moving versions, and the README links to it.

The licence is MIT, stated in pyproject.toml as the classifier "License :: OSI Approved :: MIT License". MIT is permissive: it allows use, modification and redistribution, including in closed-source products, provided the copyright notice and licence text are preserved. That is a summary of the licence text, not legal advice. If your organisation has rules about attribution in distributed binaries, check the LICENSE file and your own policy.

Editorial conclusion

Adopt Flask-SocketIO when you already have a Flask app and need server-pushed events with named messages and client-side reconnection handled for you. Do not adopt it if the other end speaks plain WebSocket, or if you want a standalone realtime service with no web framework around it, in which case python-socketio directly is the smaller dependency. Before committing, verify two things: that your deployment can route a stateful Socket.IO connection to one process, since the README does not cover multi-worker setups, and that your Flask and python-socketio versions clear the 2.1.0 and 5.12.0 floors in pyproject.toml.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. miguelgrinberg/Flask-SocketIO on GitHub
4. README
5. Releases