Install & Compatibility
Where this runs
tested against v16.1.1 · 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.316s · 19.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.284s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
serve
✓ from websockets import serve
Ensure correct import path to avoid 'NameError'
connect
✓ from websockets import connect
Ensure correct import path to avoid 'NameError'
A simple WebSocket server that echoes messages received from clients.
import asyncio
from websockets import serve
async def handler(websocket, path):
async for message in websocket:
await websocket.send(f'Hello, {message}!')
async def main():
async with serve(handler, 'localhost', 8765):
await asyncio.Future() # Run forever
if __name__ == '__main__':
asyncio.run(main())
Errors
Common errors & fixes
ConnectionRefusedError: [Errno 111] Connection refused
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.
fixEnsure the WebSocket server is active and reachable at the correct host and port before the client attempts to connect.
RuntimeError: Event loop is closed
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.
fixEnsure that `asyncio.run()` is called only once to manage the event loop, or explicitly manage the loop lifecycle to avoid using a closed loop.
websockets.exceptions.WebSocketProtocolError: WebSocket connection upgrade failed (400 Bad Request)
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.
fixReview the client's handshake request (e.g., headers, URL) and server logs to identify and resolve the specific protocol discrepancy.
ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
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.
fixVerify 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).
TypeError: a bytes-like object is required, not 'str'
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.
fixEncode strings to bytes before sending (`my_string.encode('utf-8')`) and decode received bytes to strings (`my_bytes.decode('utf-8')`) as appropriate. Upgrade
Version history
17.1latest on PyPI · released Aug 26, 2026
Audit
Dependencies
asynciorequiredRequired for asynchronous operations in Python 3.10+