What is `websockets`?

websockets is a library for building WebSocket_ servers and clients in Python
with a focus on correctness, simplicity, robustness, and performance.

.. _WebSocket: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API

Built on top of asyncio, Python's standard asynchronous I/O framework, the
default implementation provides an elegant coroutine-based API.

An implementation on top of threading and a Sans-I/O implementation are also
available.

Documentation is available on Read the Docs. <https://websockets.readthedocs.io/>_

.. copy-pasted because GitHub doesn't support the include directive

Here's an echo server with the asyncio API:

.. code:: python

#!/usr/bin/env python

import asyncio
from websockets.asyncio.server import serve

async def echo(websocket):
    async for message in websocket:
        await websocket.send(message)

async def main():
    async with serve(echo, "localhost", 8765) as server:
        await server.serve_forever()

asyncio.run(main())

Here's how a client sends and receives messages with the threading API:

.. code:: python

#!/usr/bin/env python

from websockets.sync.client import connect

def hello():
    with connect("ws://localhost:8765") as websocket:
        websocket.send("Hello world!")
        message = websocket.recv()
        print(f"Received: {message}")

hello()

Does that look good?

Get started with the tutorial! <https://websockets.readthedocs.io/en/stable/intro/index.html>_

Why should I use `websockets`?

The development of websockets is shaped by four principles:

Correctness: websockets is heavily tested for compliance with
:rfc:6455. Continuous integration fails under 100% branch coverage.
Simplicity: all you need to understand is msg = await ws.recv() and
await ws.send(msg). websockets takes care of managing connections
so you can focus on your application.
Robustness: websockets is built for production. For example, it was
the only library to handle backpressure correctly_ before the issue
became widely known in the Python community.
Performance: memory usage is optimized and configurable. A C extension
accelerates expensive operations. It's pre-compiled for Linux, macOS and
Windows and packaged in the wheel format for each system and Python version.

Documentation is a first class concern in the project. Head over to Read the Docs_ and see for yourself.

.. _Read the Docs: https://websockets.readthedocs.io/
.. _handle backpressure correctly: https://vorpus.org/blog/some-thoughts-on-asynchronous-api-design-in-a-post-asyncawait-world/#websocket-servers

Why shouldn't I use `websockets`?

If you prefer callbacks over coroutines: websockets was created to
provide the best coroutine-based API to manage WebSocket connections in
Python. Pick another library for a callback-based API.
If you're looking for a mixed HTTP / WebSocket library: websockets aims
at being an excellent implementation of :rfc:6455: The WebSocket Protocol
and :rfc:7692: Compression Extensions for WebSocket. Its support for HTTP
is minimal — just enough for an HTTP health check.

If you want to do both in the same server, look at HTTP + WebSocket servers
that build on top of websockets to support WebSocket connections, like
uvicorn_ or Sanic_.