Welcome to asyncwebsockets’s documentation!

asyncwebsockets is a Python 3.6+ library for interacting with websockets over the internet from asynchronous code. asyncwebsockets is designed around anyio, allowing it to work with multiple async backends without any modifications.

asyncwebsockets supports client and server mode.


To install the latest stable version:

$ pip install asyncwebsockets

To install the latest development version:

$ pip install git+https://github.com/Fuyukai/asyncwebsockets.git#egg=asyncwebsockets

Basic Usage

Client connection

To open a new websocket connection to a server, use open_websocket():

async with await asyncwebsockets.client.open_websocket(url, headers=None, subprotocols=None)[source]

Opens a websocket.

This async context manager returns a new Websocket, which is the main object used for communication with the server.

You can use create_websocket() if using a context manager is inconvenient, but then you’re responsible for closing it.

await asyncwebsockets.client.create_websocket(url, ssl=None, headers=None, subprotocols=None)[source]

A more low-level form of open_websocket. You are responsible for closing this websocket.

The functions create_websocket_client() and open_websocket.client() accept an existing socket instead of a URL.

async with await asyncwebsockets.client.open_websocket_client(sock, addr, path, headers=None, subprotocols=None)[source]

Create a websocket on top of a socket.

await asyncwebsockets.client.create_websocket_client(sock, addr, path, headers=None, subprotocols=None)[source]

A more low-level form of create_websocket_client. You are responsible for closing this websocket.

Server connection

Likewise, create_websocket_server() and open_websocket.server() accept an existing socket to act as a Websocket server.

async with await asyncwebsockets.server.open_websocket_server(sock, filter=None)[source]

A context manager which serves this websocket.


filter – an async callback which accepts the connection request

and returns a bool, or an explicit Accept/Reject message.

await asyncwebsockets.server.create_websocket_server(sock, filter=None)[source]

A more low-level form of open_websocket_server. You are responsible for closing this websocket.

asyncwebsockets does not provide server equivalents of open_websocket() or create_websocket(); use whatever method is most convenient for your code.

Data transfer

After being established, a Websocket connection is bidirectional and does no longer distinguish between client and server roles.

You get new events from the websocket by async iteration over the websocket object:

async for evt in websocket:
    print(type(evt))  # handle event appropriately

See the wsproto.events documentation for message types.

You can send data (strings or bytes) to the websocket in response with ClientWebsocket.send_message():

from wsproto.events import TextMessage

async for evt in websocket:
   if isinstance(evt, TextMessage):
      await websocket.send("Thanks for saying '%s'!" % (evt.data,))
await Websocket.send(data, final=True)[source]

Sends some data down the connection.

In short, you receive TextMessage or ByteMessage messages, depending on the payload. You can also filter for Message instances, and discern between strings and bytes by checking the type of the .data attribute.

Finally, the websocket can be closed with the usage of ClientWebsocket.close():

await websocket.close(1000, reason="Goodbye!")
await Websocket.close(code=1006, reason='Connection closed')[source]

Closes the websocket.

Event Listing

Events are the standard wsproto events.



  • Add server mode

  • Add ability to take over an existing socket


  • Adapt to current wsproto design


  • Redesign API, again, hopefully for the last time.


  • Redesign API significantly.


  • Initial release.