Add a WebSocket Route to your Flask 2.x Application

The WebSocket protocol was standardized 10 years ago (in 2011, can you believe it?) so I'm sure for many of it you does not need an introduction. But in case you are not familiar with it, WebSocket is an extension to the HTTP protocol that provides a permanent, bi-directional communication channel between a client and the server, where both sides can send and receive data in real time, free of the constraints of the request/response cycle of HTTP.

Flask, being a minimalist web framework, does not have WebSocket support built-in. The old Flask-Sockets extension, which has not been maintained in the last few years, provided support for this protocol. My own Flask-SocketIO extension has also been a favorite, but this is Socket.IO, which is a more complex protocol that combines WebSocket and HTTP.

The good news is that if you are using Flask 2 you now have a new extension (also created by myself) called Flask-Sock, which provides modern WebSocket support for your application. In this article I'm going to show you how to work with this extension.

This article was voted by my supporters on Patreon. Would you like to support my work, and as a thank you be able to vote on my future articles and also have access to a chat room where I hang out? Become a Patron!

Introducing the Flask-Sock Extension

The Flask-Sock extension is installed with pip:

pip install flask-sock

The extension is added to your Flask application by creating a Sock() instance. If you have a global app object, you can use the direct initialization method:

sock = Sock(app)

If instead you create your application instance in a factory function, then the two-step initialization method works as well:

sock = Sock()

def create_app():
    app = Flask(__name__)

The sock instance has a route decorator, that works pretty much like Flask's own, but it adds the WebSocket protocol handshake so that the route can speak WebSocket instead of HTTP. Here is a simple server that echoes back to the client anything it sends:

def echo(ws):
    while True:
        data = ws.receive()

The ws object that is passed to the route is the actual WebSocket connection, which the function can use to exchange information with the client through the send() and receive() methods. It goes without saying that when multiple clients are connected at the same time, each gets its own ws object, and the communication between the server and each client is private.

Looking at the code example above, the main difference between a Flask route and a WebSocket route is that the WebSocket function is designed to run for a long time. WebSocket connections often last for as long as the user has a page in the browser open, so it may be several minutes or even hours. Unlike standard HTTP routes, your WebSocket handler will very likely have to be implemented with a loop, so that it remains active for as long as it is needed. The WebSocket function is not expected to return a response, the Flask-Sock extension takes care of generating the response as required by the WebSocket protocol.

How do you end a WebSocket connection? The most common situation is that the user navigates away from the page that created the connection, At this point the browser will close the WebSocket, and from then on the ws.receive() and ws.send() methods are going to raise a ConnectionClosed exception, which is automatically handled by the Flask-Sock extension to end the route gracefully. You can catch this exception in the route to perform custom cleanup if necessary.

A second way to end the WebSocket connection occurs when the server initiates the close. To do this, the WebSocket route needs to call ws.close(), or alternatively, just exit the function.

The ws.route decorator is fully integrated with Flask, and in fact, it uses the app.route decorator internally. In particular, all these things work:

  • Variable components in the URL. If your URL has variables, the ws argument must be included before those variables in the function definition.
  • Additional decorators. You can add any decorators that are designed to work with Flask routes, such as Flask-Login's login_required and any others.
  • Before and after request handlers. These are invoked for WebSocket routes as well.
  • current_app, request, g and session. These work the same as in Flask routes, with one exception regarding the session variable, explained below.

An important feature of HTTP that is not available in WebSocket is the ability to set cookies. In HTTP, cookies are set in the response headers. WebSocket does not use an HTTP response, so it is not possible to set a cookie when the WebSocket connection ends. This means that changes made to the session object in the WebSocket handler function are not saved.

Running your Flask + WebSocket server

To run your WebSocket enabled web server during development, just run your application in the way you normally do. Both the flask run and app.run() methods of running the server are compatible with Flask-Sock.

To run your Flask + WebSocket server in production you can use Gunicorn. You will normally want to enable multithreading, because as discussed earlier, a WebSocket route will run for a long time, and without threads each WebSocket connection would consume an entire worker. The following example creates a Gunicorn server with four workers, each using 100 threads, allowing a maximum of 400 active WebSocket connections (though you will always want to leave some threads available to handle other HTTP requests):

gunicorn -b --workers 4 --threads 100 module:app

If you prefer to use a greenlet based asynchronous web server, Flask-Sock is also compatible with eventlet and gevent. The documentation has all the details. The uWSGI web server is currently not supported.

A Complete Example

Let's have a look at a complete example. Here is the Flask application code:

from flask import Flask, render_template
from flask_sock import Sock

app = Flask(__name__)
sock = Sock(app)

def index():
    return render_template('index.html')

def echo(sock):
    while True:
        data = sock.receive()

This is based in the echo server code shown above. The application has a root URL that returns the index.html client page, and a /echo route that implements a WebSocket echo endpoint.

Here is the index.html page, which you have to save in a templates subdirectory:

<!doctype html>
    <title>Flask-Sock Demo</title>
    <h1>Flask-Sock Demo</h1>
    <div id="log"></div>
    <form id="form">
      <label for="text">Input: </label>
      <input type="text" id="text" autofocus>
      const log = (text, color) => {
        document.getElementById('log').innerHTML += `<span style="color: ${color}">${text}</span><br>`;

      const socket = new WebSocket('ws://' + location.host + '/echo');
      socket.addEventListener('message', ev => {
        log('<<< ' + ev.data, 'blue');
      document.getElementById('form').onsubmit = ev => {
        const textField = document.getElementById('text');
        log('>>> ' + textField.value, 'red');
        textField.value = '';

The HTML page includes a <script> section with the client-side logic. The log() auxiliary function writes a string to the page, using the given color. This is used to write outgoing data in red, and incoming data in blue, as you can see in the screenshot below:

Flask-Sock Echo Server Demo

The application uses the WebSocket class provided by the browser to make a connection to the /echo endpoint. It then installs a listener for the message event, which fires whenever the server sends data through the connection. The handler prints the data to the page. The page has a form with an <input> element that accepts text from the user. A second event handler is defined on the submit event for the form. The handler for this event logs the text entered by the user to the page, and then writes it to the WebSocket connection, using its send() method.

To try out this application, save the Python file as app.py and the HTML file as index.html in a templates subdirectory. Then run the application with flask run. Connect with your browser at the http://localhost:5000 URL to use the application.

What Flask-Sock Doesn't Do

Flask-Sock is designed to be a simple extension to implement WebSocket communication between a client and the server. It is not a goal of this extension to implement advanced workflows involving the broadcasting of messages to all or to subsets of clients. Your application can implement this if desired, but if you need something of this complexity you may be better off using Flask-SocketIO. I have written an article about it too!


  • #26 Miguel Grinberg said 2022-06-14T13:29:29Z

    @Amine: your cron job needs to communicate with the server process in some way and pass the data. The cron job process does not have access to the ws instances for your clients, so it cannot send to them directly.

  • #27 Quantum-Quant said 2022-06-16T21:42:30Z

    Hi Miguel, thank you for this great tutorial! In the documentation for Flask-SocketIO, you explicitly mention that gunicorn doesn't support running multiple workers unless one uses a load balancer such as nginx (https://flask-socketio.readthedocs.io/en/latest/deployment.html#using-multiple-workers). In this tutorial, however, it seems that Flask-Sock doesn't have this restriction. Is my understanding correct? And if so, why is that?

    Thank you!

  • #28 Miguel Grinberg said 2022-06-16T22:52:42Z

    @Quantum: Flask-Sock implements a WebSocket connection, not Socket.IO which is much more complex. For example, Flask-Sock does not handle broadcasting or rooms.

  • #29 Zaheer Abbas said 2022-07-22T06:59:23Z

    Hi miguel, I wanted to save data received from websockets to file, But when I use the following code:

    @sock.route("/media-stream") def echo(sock): print("Connection opened") id = uuid.uuid4().hex while True: data = sock.receive() decoded_data = base64.b64decode(data) print(decoded_data) wf = wave.open(id + ".wav", "rb") wf.write(decoded_data)

    The client reconnects every time and does not work, can you please suggest how can I go about doing this using flask-sock

  • #30 Miguel Grinberg said 2022-07-22T13:31:32Z

    @Zaheer: you need to fix your code. You are opening the file for read access, not write. You are also opening a new file for every message, without ever closing anything. You should open a single instance of the wave file outside the loop, in my opinion.

  • #31 Amine said 2022-08-16T12:48:18Z

    Hello Miguel, i'm using flask-sock for a project i'm working on. And i noticed that with multiple users, only the last one to access the web app receives the messages. The work flow is setup in a way that there's a global variable that contains an empty string. It gets filled and emptied using a cronjob, and i test against its content to execute whats under the socket which is "ws.send(message)". My question is this a constraint of flask-sock? Should i switch to flask-socket-io if i want to "broadcast" to all clients connected? Not the last one to access the app if that has a name.

  • #32 Miguel Grinberg said 2022-08-16T19:14:13Z

    @Amine: This is maybe a misunderstanding on your part on how Flask-Sock works. When a client connects, the server assigns a websocket object to it and passes it to the route. This object is used to send and receive messages between the server and this client. There is no such thing as a broadcast, if you want to send the same data to multiple clients, you have to send on each of the websocket objects for the intended recipients.

  • #33 Amine said 2022-08-19T12:22:28Z

    Hello Miguel, thank you for the explanation on how flask-sock handles websocket connection. Now i understand. Turns out my problem was the usage of a global variable to execute whats under the socket route. The last client to connect would the first to receive the message ( and empty the global variable so no more messages for the rest of the clients ). I now append all websocket objects related to clients that connect to the route in a global list, and iterate through it anywhere in my code to send data to all clients. It works like a charm! Thank you.

  • #34 Mariano said 2022-09-25T16:11:46Z

    hola! Miguel<br /> I'm trying to use this library, and it works perfectly for me to send and receive data, but I'm trying to use the data outside the echo() function and I can't, is there any way to use the data variable in other parts of the code? My code receives a video frame in a byte string, I send it to the video_feed() function to display it in the html (THIS ONLY WORKS IF I COMMENT THE DECORATOR @sock.route('/')) if I comment it works fine but I can't receive data, any ideas? anything would help me, thank you very much and sorry for my long question.

    @sock.route('/') -> (If I comment this line it works but logically I am left without receiving data)
    def echo():
            global data
            img= np.fromstring(data, np.uint8)
            img = cv2.imdecode(np.frombuffer(img, dtype=np.byte), flags=cv2.IMREAD_COLOR)
            _, frame = cv2.imencode('.jpeg', img) 
            yield (b'--frame\r\nContent-Type: image/jpeg\r\n\r\n' + frame.tobytes() + b'\r\n')
            img= np.fromstring(data, np.uint8)
            img = cv2.imdecode(np.frombuffer(img, dtype=np.byte), flags=cv2.IMREAD_COLOR)
            _, frame = cv2.imencode('.jpeg', img) 
            yield (b'--frame\r\nContent-Type: image/jpeg\r\n\r\n' + frame.tobytes() + b'\r\n')
    def video_feed():
        return Response(echo(),  -------> using here
            mimetype = "multipart/x-mixed-replace; boundary=frame")
  • #35 Miguel Grinberg said 2022-09-25T21:48:43Z

    @Mariano: I don't really understand what you are trying to do, but the yield keyword is used in Flask streaming responses. This is not for websocket routes created with Flask-Sock. Please check the examples in the Flask-Sock repository and the official documentation to learn how to use this extension.

Leave a Comment