Skip to main content

WebSocket client for Python with low level API options

Project description

docs Build Status codecov PyPI Downloads PyPI version


websocket-client is a WebSocket client for Python. It provides access to low level APIs for WebSockets. websocket-client implements version hybi-13 of the WebSocket protocol. This client does not currently support the permessage-deflate extension from RFC 7692.


This project's documentation can be found at


Please see the contribution guidelines


You can use either python3 install or pip3 install websocket-client to install. This module is tested on Python 3.6+.

There are several optional dependencies that can be installed to enable specific websocket-client features.

  • To install python-socks for proxy usage and wsaccel for a minor performance boost, use: pip3 install websocket-client[optional]
  • To install websockets to run unit tests using the local echo server, use: pip3 install websocket-client[test]
  • To install Sphinx and sphinx_rtd_theme to build project documentation, use: pip3 install websocket-client[docs]

Footnote: Some shells, such as zsh, require you to escape the [ and ] characters with a \.

Usage Tips

Check out the documentation's FAQ for additional guidelines:

Known issues with this library include lack of WebSocket Compression support (RFC 7692) and minimal threading documentation/support.


The send and validate_utf8 methods can sometimes be bottleneck. You can disable UTF8 validation in this library (and receive a performance enhancement) with the skip_utf8_validation parameter. If you want to get better performance, install wsaccel. While websocket-client does not depend on wsaccel, it will be used if available. wsaccel doubles the speed of UTF8 validation and offers a very minor 10% performance boost when masking the payload data as part of the send process. Numpy used to be a suggested performance enhancement alternative, but issue #687 found it didn't help.


Many more examples are found in the examples documentation.

Long-lived Connection

Most real-world WebSockets situations involve longer-lived connections. The WebSocketApp run_forever loop automatically tries to reconnect when a connection is lost, and provides a variety of event-based connection controls.

import websocket
import _thread
import time

def on_message(ws, message):

def on_error(ws, error):

def on_close(ws, close_status_code, close_msg):
    print("### closed ###")

def on_open(ws):
    def run(*args):
        for i in range(3):
            ws.send("Hello %d" % i)
        print("thread terminating...")
    _thread.start_new_thread(run, ())

if __name__ == "__main__":
    ws = websocket.WebSocketApp("ws://",


Short-lived Connection

This is if you want to communicate a short message and disconnect immediately when done. For example, if you want to confirm that a WebSocket server is running and responds properly to a specific request.

from websocket import create_connection
ws = create_connection("ws://")
print("Sending 'Hello, World'...")
ws.send("Hello, World")
result =  ws.recv()
print("Received '%s'" % result)

If you want to customize socket options, set sockopt, as seen below:

from websocket import create_connection
ws = create_connection("ws://",
                        sockopt=((socket.IPPROTO_TCP, socket.TCP_NODELAY),))


Thanks to @battlemidget and @ralphbean for helping migrate this project to Python 3.

Project details

Release history Release notifications | RSS feed

This version


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

websocket-client-1.2.3.tar.gz (46.4 kB view hashes)

Uploaded source

Built Distribution

websocket_client-1.2.3-py3-none-any.whl (53.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page