websockets

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

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.

pip install websockets

Common errors

error ConnectionRefusedError: [Errno 111] Connection refused ↓

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.

fix

Ensure the WebSocket server is active and reachable at the correct host and port before the client attempts to connect.

error RuntimeError: Event loop is closed ↓

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.

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.

error websockets.exceptions.WebSocketProtocolError: WebSocket connection upgrade failed (400 Bad Request) ↓

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.

fix

Review the client's handshake request (e.g., headers, URL) and server logs to identify and resolve the specific protocol discrepancy.

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

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.

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).

error TypeError: a bytes-like object is required, not 'str' ↓

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.

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.

Warnings

breaking websockets 16.0 requires Python ≥ 3.10; 15.0 is the last version supporting Python 3.9. ↓

fix Upgrade to Python 3.10 or later.

breaking Receiving the request path in the second parameter of connection handlers is deprecated; use 'path = request.path' inside the handler function. ↓

fix Update handler functions to access 'path' via 'request.path'.

gotcha Ensure correct import paths to avoid 'NameError' when importing 'serve' or 'connect'. ↓

fix Use 'from websockets import serve' and 'from websockets import connect'.

breaking 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. ↓

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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.20s 19.1M

3.10 slim (glibc) - - 0.14s 20M

3.11 alpine (musl) - - 0.30s 21.2M

3.11 slim (glibc) - - 0.25s 22M

3.12 alpine (musl) - - 0.47s 13.0M

3.12 slim (glibc) - - 0.46s 13M

3.13 alpine (musl) - - 0.47s 12.6M

3.13 slim (glibc) - - 0.41s 13M

3.9 alpine (musl) - - 0.17s 18.6M

3.9 slim (glibc) - - 0.14s 19M

Imports

serve
```
from websockets import serve
```
Ensure correct import path to avoid 'NameError'
connect
```
from websockets import connect
```
Ensure correct import path to avoid 'NameError'

Quickstart stale last tested: 2026-04-23

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())