{"id":340,"library":"websocket-client","title":"websocket-client","description":"A Python library for WebSocket communication, providing both high-level and low-level APIs. Current version: 1.9.0. Maintained with regular updates.","status":"active","version":"1.9.0","language":"python","source_language":"en","source_url":"https://github.com/websocket-client/websocket-client","tags":["websocket","client","python","networking","communication"],"install":[{"cmd":"pip install websocket-client","lang":"bash","label":"Install websocket-client"}],"dependencies":[{"reason":"Enables proxy support","package":"python-socks","optional":true},{"reason":"Improves performance","package":"wsaccel","optional":true},{"reason":"Required for running unit tests","package":"websockets","optional":true},{"reason":"Needed for building project documentation","package":"Sphinx","optional":true},{"reason":"Provides theme for Sphinx documentation","package":"sphinx_rtd_theme","optional":true},{"reason":"Useful for automatic reconnection with run_forever","package":"rel","optional":true}],"imports":[{"note":"Ensure correct import path to avoid ImportError","symbol":"WebSocketApp","correct":"from websocket import WebSocketApp"}],"quickstart":{"code":"import websocket\n\ndef on_message(ws, message):\n    print(message)\n\ndef on_error(ws, error):\n    print(error)\n\ndef on_close(ws, close_status_code, close_msg):\n    print('### closed ###')\n\ndef on_open(ws):\n    print('Opened connection')\n\nif __name__ == '__main__':\n    websocket.enableTrace(True)\n    ws = websocket.WebSocketApp('wss://api.gemini.com/v1/marketdata/BTCUSD',\n                              on_open=on_open,\n                              on_message=on_message,\n                              on_error=on_error,\n                              on_close=on_close)\n    ws.run_forever(dispatcher=rel, reconnect=5)\n    rel.signal(2, rel.abort)\n    rel.dispatch()","lang":"python","description":"A simple example demonstrating how to establish a WebSocket connection and handle messages."},"warnings":[{"fix":"Install the 'rel' package and pass it as the dispatcher to 'run_forever'.","message":"The 'run_forever' method requires a dispatcher for automatic reconnection. Without it, the method will not function as intended.","severity":"breaking","affected_versions":"1.9.0"},{"fix":"Use 'pip install websocket-client\\[optional\\]' to install optional dependencies.","message":"Some shells, such as zsh, require escaping of '[' and ']' characters in pip install commands.","severity":"gotcha","affected_versions":"1.9.0"}],"env_vars":null,"last_verified":"2026-05-12T13:10:28.569Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install websocket-client`.","cause":"The `websocket-client` library is not installed in the current Python environment, or the import statement is incorrect for the installed library.","error":"ModuleNotFoundError: No module named 'websocket'"},{"fix":"Ensure the WebSocket connection is successfully established before attempting to send data. For `WebSocketApp`, send messages from within the `on_open` callback: \n```python\nimport websocket\ndef on_open(ws):\n    ws.send('Hello')\n\nws_app = websocket.WebSocketApp('ws://echo.websocket.org/', on_open=on_open)\nws_app.run_forever()\n```","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.","error":"AttributeError: 'NoneType' object has no attribute 'send'"},{"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.","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.","error":"ConnectionRefusedError: [Errno 111] Connection refused"},{"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:\n```python\nimport websocket\nws = websocket.create_connection('wss://example.com/ws', header={'Authorization': 'Bearer YOUR_TOKEN', 'Origin': 'https://example.com'})\n```","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).","error":"websocket._exceptions.WebSocketBadStatusException: Handshake status 400"},{"fix":"For development/testing (use with caution), disable certificate verification: \n```python\nimport websocket\nimport ssl\nws = websocket.create_connection('wss://localhost:8080', sslopt={'cert_reqs': ssl.CERT_NONE})\n```\nFor production, ensure the server uses a valid, trusted SSL certificate and the client's system has the necessary root certificates.","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.","error":"ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3.5,"disk_size":"18.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":3.5,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":4.1,"disk_size":"20.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":4.1,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":4,"disk_size":"12.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":4,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":4.4,"disk_size":"11.9M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":4.4,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3.4,"disk_size":"17.9M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":3.4,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}