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 https://websocket-client.readthedocs.io/

Please see the contribution guidelines

You can use pip install websocket-client to install, or pip install -e . to install from a local copy of the code. This module is tested on Python 3.9+.

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: pip install websocket-client[optional]
• To install websockets to run unit tests using the local echo server, use: pip install websocket-client[test]
• To install Sphinx and sphinx_rtd_theme to build project documentation, use: pip install websocket-client[docs]

While not a strict dependency, rel is useful when using run_forever with automatic reconnect. Install rel with pip install rel.

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

Check out the documentation's FAQ for additional guidelines: https://websocket-client.readthedocs.io/en/latest/faq.html

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.

Most real-world WebSockets situations involve longer-lived connections. The WebSocketApp run_forever loop will automatically try to reconnect to an open WebSocket connection when a network connection is lost if it is provided with:

• a dispatcher argument (async dispatcher like rel or pyevent)
• a non-zero reconnect argument (delay between disconnection and attempted reconnection)

run_forever provides a variety of event-based connection controls using callbacks like on_message and on_error. run_forever does not automatically reconnect if the server closes the WebSocket gracefully (returning a standard websocket close code). This is the logic behind the decision. Customizing behavior when the server closes the WebSocket should be handled in the on_close callback. This example uses rel for the dispatcher to provide automatic reconnection.

import websocket import _thread import time import rel def on_message(ws, message): print(message) def on_error(ws, error): print(error) def on_close(ws, close_status_code, close_msg): print("### closed ###") def on_open(ws): print("Opened connection") if __name__ == "__main__": websocket.enableTrace(True) ws = websocket.WebSocketApp("wss://api.gemini.com/v1/marketdata/BTCUSD", on_open=on_open, on_message=on_message, on_error=on_error, on_close=on_close) ws.run_forever(dispatcher=rel, reconnect=5) # Set dispatcher to automatic reconnection, 5 second reconnect delay if connection closed unexpectedly rel.signal(2, rel.abort) # Keyboard Interrupt rel.dispatch()

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://echo.websocket.events/") print(ws.recv()) print("Sending 'Hello, World'...") ws.send("Hello, World") print("Sent") print("Receiving...") result = ws.recv() print("Received '%s'" % result) ws.close()