Install & Compatibility
Where this runs
tested against v1.9.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.104s · 18.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.096s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WebSocketApp
✓ from websocket import WebSocketApp
Ensure correct import path to avoid ImportError
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()
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'websocket'
The `websocket-client` library is not installed in the current Python environment, or the import statement is incorrect for the installed library.
fixInstall the library using pip: `pip install websocket-client`.
AttributeError: 'NoneType' object has no attribute 'send'
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.
fixEnsure the WebSocket connection is successfully established before attempting to send data. For `WebSocketApp`, send messages from within the `on_open` callback:
```python
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()
``` ConnectionRefusedError: [Errno 111] Connection refused
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.
fixVerify 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.
websocket._exceptions.WebSocketBadStatusException: Handshake status 400
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).
fixInspect 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:
```python
import websocket
ws = websocket.create_connection('wss://example.com/ws', header={'Authorization': 'Bearer YOUR_TOKEN', 'Origin': 'https://example.com'})
``` ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
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.
fixFor development/testing (use with caution), disable certificate verification:
```python
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. Upgrade
Version history
1.9.0latest on PyPI · released Oct 7, 2025
Audit
Dependencies
python-socksoptionalEnables proxy support
wsacceloptionalImproves performance
websocketsoptionalRequired for running unit tests
SphinxoptionalNeeded for building project documentation
sphinx_rtd_themeoptionalProvides theme for Sphinx documentation
reloptionalUseful for automatic reconnection with run_forever