websockets

websockets is a Python library for building WebSocket servers and clients with a focus on correctness, simplicity, robustness, and performance. Its default implementation is built on asyncio and exposes an elegant coroutine-based API, while additional threading and Sans-I/O implementations let you integrate WebSockets into any concurrency model.

Heavily tested for compliance with RFC 6455 and RFC 7692, websockets enforces 100% branch coverage in CI and ships a C extension with prebuilt wheels for fast, memory-efficient production deployments. All you need to remember is await ws.recv() and await ws.send(msg) — the library manages connections, ping/pong keepalives, backpressure, and clean closes for you.

What You Get

• An asyncio implementation with a coroutine-based serve/connect API and async iteration over incoming messages
• A synchronous threading implementation for scripts and codebases that do not use asyncio
• A Sans-I/O core (websockets.protocol) you can drive from any I/O framework
• A C speedups extension with prebuilt wheels for Linux, macOS, and Windows across Python versions
• Built-in permessage-deflate compression, basic-auth helpers, proxy support, and a websockets CLI client

Common Use Cases

• Serving realtime updates to browser or mobile clients over a persistent WebSocket connection
• Writing a WebSocket client to consume a streaming API or exchange feed
• Building the WebSocket transport layer underneath higher-level frameworks such as uvicorn or Sanic
• Bridging services with low-latency bidirectional messaging without polling

Under The Hood

Architecture — websockets is organized around a Sans-I/O core: src/websockets/protocol.py together with client.py and server.py implement the RFC 6455 state machine as pure functions over bytes and events, entirely decoupled from any I/O. Concrete transports wrap this core — src/websockets/asyncio/ provides the asyncio Connection, ServerConnection, and ClientConnection classes plus serve/connect, src/websockets/sync/ provides the threading equivalents, and src/websockets/legacy/ retains the previous asyncio implementation for compatibility. Framing, headers, URIs, and HTTP/1.1 handshake handling are factored into dedicated modules (frames.py, headers.py, uri.py, http11.py), and the public surface is re-exported lazily via imports.lazy_import in __init__.py. Tech Stack — Pure Python (requires Python >=3.11) built on the standard-library asyncio and threading modules with no runtime third-party dependencies; an optional C extension (speedups.c) accelerates frame masking and is shipped as prebuilt wheels via cibuildwheel. Packaging uses setuptools with configuration in pyproject.toml, and the project ships a py.typed marker for full type-checker support. Code Quality — Exceptionally strong: 59 test modules under tests/ mirror the source layout, CI fails under 100% branch coverage, and the codebase is fully type-annotated with from __future__ import annotations and precise typing throughout. Naming is consistent, docstrings are thorough, and error handling is modeled by a dedicated exceptions.py hierarchy (ConnectionClosed, InvalidHandshake, and friends). API Design — The public API is deliberately minimal and ergonomic: async with serve(handler, host, port) for servers, async with connect(uri) for clients, and just send/recv plus async iteration for messages. The same conceptual API is mirrored across the asyncio and threading implementations, documentation on Read the Docs is a first-class concern with a tutorial and reference, and connection management, backpressure, and keepalive are handled automatically so little boilerplate is required.