websocket-client

1.9.0 verified Tue May 12 auth: no python install: verified quickstart: stale

A Python library for WebSocket communication, providing both high-level and low-level APIs. Current version: 1.9.0. Maintained with regular updates.

pip install websocket-client

Common errors

error ModuleNotFoundError: No module named 'websocket' ↓

cause The `websocket-client` library is not installed in the current Python environment, or the import statement is incorrect for the installed library.

fix

Install the library using pip: pip install websocket-client.

error AttributeError: 'NoneType' object has no attribute 'send' ↓

cause Attempting to call `send()` on a `WebSocketApp` object that is `None` or on a connection object (from `create_connection`) that failed to initialize successfully, meaning the connection was not established.

fix

Ensure the WebSocket connection is successfully established before attempting to send data. For WebSocketApp, send messages from within the on_open callback:

import websocket
def on_open(ws):
    ws.send('Hello')

ws_app = websocket.WebSocketApp('ws://echo.websocket.org/', on_open=on_open)
ws_app.run_forever()

error ConnectionRefusedError: [Errno 111] Connection refused ↓

cause The client failed to connect to the WebSocket server because the server is not running, is not listening on the specified port, or a firewall is blocking the connection.

fix

Verify the WebSocket server's URL (host and port), ensure the server application is running and accessible from the client's machine, and check any firewall configurations on both client and server.

error websocket._exceptions.WebSocketBadStatusException: Handshake status 400 ↓

cause The server rejected the WebSocket handshake due to an invalid request, authentication failure, missing required headers, or an internal server error on the server side. (Status codes like 401, 403, 500 are also common).

fix

Inspect the server's logs for specific reasons. Ensure the WebSocket URL is correct and any required headers (e.g., authentication tokens, Origin) are properly included in the header parameter:

import websocket
ws = websocket.create_connection('wss://example.com/ws', header={'Authorization': 'Bearer YOUR_TOKEN', 'Origin': 'https://example.com'})

error ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed ↓

cause The client's SSL/TLS handshake failed because it could not verify the server's identity, often due to a self-signed, expired, or untrusted SSL certificate on the server.

fix

For development/testing (use with caution), disable certificate verification:

import websocket
import ssl
ws = websocket.create_connection('wss://localhost:8080', sslopt={'cert_reqs': ssl.CERT_NONE})

For production, ensure the server uses a valid, trusted SSL certificate and the client's system has the necessary root certificates.

Warnings

breaking The 'run_forever' method requires a dispatcher for automatic reconnection. Without it, the method will not function as intended. ↓

fix Install the 'rel' package and pass it as the dispatcher to 'run_forever'.

gotcha Some shells, such as zsh, require escaping of '[' and ']' characters in pip install commands. ↓

fix Use 'pip install websocket-client\[optional\]' to install optional dependencies.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.09s 18.4M

3.10 slim (glibc) - - 0.05s 19M

3.11 alpine (musl) - - 0.17s 20.4M

3.11 slim (glibc) - - 0.12s 21M

3.12 alpine (musl) - - 0.13s 12.2M

3.12 slim (glibc) - - 0.13s 13M

3.13 alpine (musl) - - 0.12s 11.9M

3.13 slim (glibc) - - 0.12s 12M

3.9 alpine (musl) - - 0.09s 17.9M

3.9 slim (glibc) - - 0.07s 18M

Imports

WebSocketApp
```
from websocket import WebSocketApp
```
Ensure correct import path to avoid ImportError

Quickstart stale last tested: 2026-04-23

A simple example demonstrating how to establish a WebSocket connection and handle messages.

import websocket

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)
    rel.signal(2, rel.abort)
    rel.dispatch()