{"id":380,"library":"websockets","title":"websockets","description":"An implementation of the WebSocket Protocol (RFC 6455 & 7692) for Python, currently at version 16.0, with a release cadence of approximately every 6 months.","status":"active","version":"16.0","language":"python","source_language":"en","source_url":"https://github.com/python-websockets/websockets","tags":["websockets","asyncio","Python 3.10+"],"install":[{"cmd":"pip install websockets","lang":"bash","label":"Install websockets"}],"dependencies":[{"reason":"Required for asynchronous operations in Python 3.10+","package":"asyncio"}],"imports":[{"note":"Ensure correct import path to avoid 'NameError'","symbol":"serve","correct":"from websockets import serve"},{"note":"Ensure correct import path to avoid 'NameError'","symbol":"connect","correct":"from websockets import connect"}],"quickstart":{"code":"import asyncio\nfrom websockets import serve\n\nasync def handler(websocket, path):\n    async for message in websocket:\n        await websocket.send(f'Hello, {message}!')\n\nasync def main():\n    async with serve(handler, 'localhost', 8765):\n        await asyncio.Future()  # Run forever\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"A simple WebSocket server that echoes messages received from clients."},"warnings":[{"fix":"Upgrade to Python 3.10 or later.","message":"websockets 16.0 requires Python ≥ 3.10; 15.0 is the last version supporting Python 3.9.","severity":"breaking","affected_versions":"16.0"},{"fix":"Update handler functions to access 'path' via 'request.path'.","message":"Receiving the request path in the second parameter of connection handlers is deprecated; use 'path = request.path' inside the handler function.","severity":"breaking","affected_versions":"13.0"},{"fix":"Use 'from websockets import serve' and 'from websockets import connect'.","message":"Ensure correct import paths to avoid 'NameError' when importing 'serve' or 'connect'.","severity":"gotcha","affected_versions":"All"},{"fix":"Examine server logs for startup errors, unhandled exceptions, or deadlocks. Verify network connectivity and port availability. Ensure `websockets.serve` is properly awaited and running without blocking issues.","message":"The application timed out. This may indicate the websockets server failed to start, became unresponsive due to an internal error or deadlock, or could not be reached by the client.","severity":"breaking","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-05-12T13:25:47.706Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Ensure the WebSocket server is active and reachable at the correct host and port before the client attempts to connect.","cause":"The WebSocket client failed to connect because the server was not running, was not listening, or was not accessible at the specified address and port.","error":"ConnectionRefusedError: [Errno 111] Connection refused"},{"fix":"Ensure that `asyncio.run()` is called only once to manage the event loop, or explicitly manage the loop lifecycle to avoid using a closed loop.","cause":"An `asyncio` operation, such as creating a new task or awaiting a coroutine, was attempted on an event loop that had already been shut down.","error":"RuntimeError: Event loop is closed"},{"fix":"Review the client's handshake request (e.g., headers, URL) and server logs to identify and resolve the specific protocol discrepancy.","cause":"The WebSocket handshake failed because the server rejected the client's request due to a protocol violation, invalid headers, or an issue on the server side.","error":"websockets.exceptions.WebSocketProtocolError: WebSocket connection upgrade failed (400 Bad Request)"},{"fix":"Verify the server's SSL certificate is valid and issued by a trusted CA, or, for testing, consider passing `ssl=False` or `ssl_context.check_hostname = False` (use with caution).","cause":"The client could not establish a secure TLS/SSL connection because the server's certificate was invalid, expired, untrusted, or did not match the hostname.","error":"ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed"},{"fix":"Encode strings to bytes before sending (`my_string.encode('utf-8')`) and decode received bytes to strings (`my_bytes.decode('utf-8')`) as appropriate.","cause":"An attempt was made to use a `str` object where `bytes` were expected (e.g., when sending data) or vice versa (e.g., when decoding received data) without proper encoding/decoding.","error":"TypeError: a bytes-like object is required, not 'str'"}],"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.2,"mem_mb":7.3,"disk_size":"19.1M"},{"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.14,"mem_mb":7.3,"disk_size":"20M"},{"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.3,"mem_mb":8.5,"disk_size":"21.2M"},{"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.25,"mem_mb":8.5,"disk_size":"22M"},{"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.47,"mem_mb":10.6,"disk_size":"13.0M"},{"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.46,"mem_mb":10.6,"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.47,"mem_mb":10.2,"disk_size":"12.6M"},{"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.41,"mem_mb":10.2,"disk_size":"13M"},{"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.17,"mem_mb":7.1,"disk_size":"18.6M"},{"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.14,"mem_mb":7.1,"disk_size":"19M"}]},"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}]}}