Changelog#

Backwards-compatibility policy#

websockets is intended for production use. Therefore, stability is a goal.

websockets also aims at providing the best API for WebSocket in Python.

While we value stability, we value progress more. When an improvement requires changing a public API, we make the change and document it in this changelog.

When possible with reasonable effort, we preserve backwards-compatibility for five years after the release that introduced the change.

When a release contains backwards-incompatible API changes, the major version is increased, else the minor version is increased. Patch versions are only for fixing regressions shortly after a release.

Only documented APIs are public. Undocumented, private APIs may change without notice.

12.0#

October 21, 2023

Backwards-incompatible changes#

websockets 12.0 requires Python ≥ 3.8.

websockets 11.0 is the last version supporting Python 3.7.

Improvements#

Made convenience imports from websockets compatible with static code analysis tools such as auto-completion in an IDE or type checking with mypy.
Accepted a plain int where an HTTPStatus is expected.
Added CloseCode.

11.0.3#

May 7, 2023

Bug fixes#

Fixed the threading implementation of servers on Windows.

11.0.2#

April 18, 2023

Bug fixes#

Fixed a deadlock in the threading implementation when closing a connection without reading all messages.

11.0.1#

April 6, 2023

Bug fixes#

Restored the C extension in the source distribution.

11.0#

April 2, 2023

Backwards-incompatible changes#

The Sans-I/O implementation was moved.

Aliases provide compatibility for all previously public APIs according to the backwards-compatibility policy.

The connection module was renamed to protocol.
The connection.Connection, server.ServerConnection, and client.ClientConnection classes were renamed to protocol.Protocol, server.ServerProtocol, and client.ClientProtocol.

Sans-I/O protocol constructors now use keyword-only arguments.

If you instantiate ServerProtocol or ClientProtocol directly, make sure you are using keyword arguments.

Closing a connection without an empty close frame is OK.

Receiving an empty close frame now results in ConnectionClosedOK instead of ConnectionClosedError.

As a consequence, calling WebSocket.close() without arguments in a browser isn’t reported as an error anymore.

serve() times out on the opening handshake after 10 seconds by default.

You can adjust the timeout with the open_timeout parameter. Set it to None to disable the timeout entirely.

New features#

websockets 11.0 introduces a implementation on top of threading.

It may be more convenient if you don’t need to manage many connections and you’re more comfortable with threading than asyncio.

It is particularly suited to client applications that establish only one connection. It may be used for servers handling few connections.

See connect() and serve() for details.

Added open_timeout to serve().
Made it possible to close a server without closing existing connections.
Added select_subprotocol to customize negotiation of subprotocols in the Sans-I/O layer.

Improvements#

Added platform-independent wheels.
Improved error handling in broadcast().
Set server_hostname automatically on TLS connections when providing a sock argument to connect().

10.4#

October 25, 2022

New features#

Validated compatibility with Python 3.11.
Added the latency property to protocols.
Changed ping to return the latency of the connection.
Supported overriding or removing the User-Agent header in clients and the Server header in servers.
Added deployment guides for more Platform as a Service providers.

Improvements#

Improved FAQ.

10.3#

April 17, 2022

Backwards-incompatible changes#

The exception attribute of Request and Response is deprecated.

Use the handshake_exc attribute of ServerProtocol and ClientProtocol instead.

See Integrate the Sans-I/O layer for details.

Improvements#

Reduced noise in logs when ssl or zlib raise exceptions.

10.2#

February 21, 2022

Improvements#

Made compression negotiation more lax for compatibility with Firefox.
Improved FAQ and quick start guide.

Bug fixes#

Fixed backwards-incompatibility in 10.1 for connection handlers created with functools.partial().
Avoided leaking open sockets when connect() is canceled.

10.1#

November 14, 2021

New features#

Added a tutorial.
Made the second parameter of connection handlers optional. It will be deprecated in the next major release. The request path is available in the path attribute of the first argument.

If you implemented the connection handler of a server as:
```
async def handler(request, path):
    ...
```
You should replace it by:
```
async def handler(request):
    path = request.path  # if handler() uses the path argument
    ...
```
Added python -m websockets --version.

Improvements#

Added wheels for Python 3.10, PyPy 3.7, and for more platforms.
Reverted optimization of default compression settings for clients, mainly to avoid triggering bugs in poorly implemented servers like AWS API Gateway.
Mirrored the entire Server API in WebSocketServer.
Improved performance for large messages on ARM processors.
Documented how to auto-reload on code changes in development.

Bug fixes#

Avoided half-closing TCP connections that are already closed.

10.0#

September 9, 2021

Backwards-incompatible changes#

websockets 10.0 requires Python ≥ 3.7.

websockets 9.1 is the last version supporting Python 3.6.

The loop parameter is deprecated from all APIs.

This reflects a decision made in Python 3.8. See the release notes of Python 3.10 for details.

The loop parameter is also removed from WebSocketServer. This should be transparent.

connect() times out after 10 seconds by default.

You can adjust the timeout with the open_timeout parameter. Set it to None to disable the timeout entirely.

The legacy_recv option is deprecated.

See the release notes of websockets 3.0 for details.

The signature of ConnectionClosed changed.

If you raise ConnectionClosed or a subclass, rather than catch them when websockets raises them, you must change your code.

A msg parameter was added to InvalidURI.

If you raise InvalidURI, rather than catch it when websockets raises it, you must change your code.

New features#

websockets 10.0 introduces a Sans-I/O API for easier integration in third-party libraries.

If you’re integrating websockets in a library, rather than just using it, look at the Sans-I/O integration guide.

Added compatibility with Python 3.10.
Added broadcast() to send a message to many clients.
Added support for reconnecting automatically by using connect() as an asynchronous iterator.
Added open_timeout to connect().
Documented how to integrate with Django.
Documented how to deploy websockets in production, with several options.
Documented how to authenticate connections.
Documented how to broadcast messages to many connections.

Improvements#

Improved logging. See the logging guide.
Optimized default compression settings to reduce memory usage.
Optimized processing of client-to-server messages when the C extension isn’t available.
Supported relative redirects in connect().
Handled TCP connection drops during the opening handshake.
Made it easier to customize authentication with check_credentials().
Provided additional information in ConnectionClosed exceptions.
Clarified several exceptions or log messages.
Restructured documentation.
Improved API documentation.
Extended FAQ.

Bug fixes#

Avoided a crash when receiving a ping while the connection is closing.

9.1#

May 27, 2021

Security fix#

websockets 9.1 fixes a security issue introduced in 8.0.

Version 8.0 was vulnerable to timing attacks on HTTP Basic Auth passwords (CVE-2021-33880).

9.0.2#

May 15, 2021

Bug fixes#

Restored compatibility of python -m websockets with Python < 3.9.
Restored compatibility with mypy.

9.0.1#

May 2, 2021

Bug fixes#

Fixed issues with the packaging of the 9.0 release.

9.0#

May 1, 2021

Backwards-incompatible changes#

Several modules are moved or deprecated.

Aliases provide compatibility for all previously public APIs according to the backwards-compatibility policy

Headers and MultipleValuesError are moved from websockets.http to websockets.datastructures. If you’re using them, you should adjust the import path.
The client, server, protocol, and auth modules were moved from the websockets package to a websockets.legacy sub-package. Despite the name, they’re still fully supported.
The framing, handshake, headers, http, and uri modules in the websockets package are deprecated. These modules provided low-level APIs for reuse by other projects, but they didn’t reach that goal. Keeping these APIs public makes it more difficult to improve websockets.

These changes pave the path for a refactoring that should be a transparent upgrade for most uses and facilitate integration by other projects.

Convenience imports from websockets are performed lazily.

While Python supports this, tools relying on static code analysis don’t. This breaks auto-completion in an IDE or type checking with mypy.

If you depend on such tools, use the real import paths, which can be found in the API documentation, for example:

from websockets.client import connect
from websockets.server import serve

New features#

Added compatibility with Python 3.9.

Improvements#

Added support for IRIs in addition to URIs.
Added close codes 1012, 1013, and 1014.
Raised an error when passing a dict to send().
Improved error reporting.

Bug fixes#

Fixed sending fragmented, compressed messages.
Fixed Host header sent when connecting to an IPv6 address.
Fixed creating a client or a server with an existing Unix socket.
Aligned maximum cookie size with popular web browsers.
Ensured cancellation always propagates, even on Python versions where CancelledError inherits Exception.

8.1#

November 1, 2019

New features#

Added compatibility with Python 3.8.

8.0.2#

July 31, 2019

Bug fixes#

Restored the ability to pass a socket with the sock parameter of serve().
Removed an incorrect assertion when a connection drops.

8.0.1#

July 21, 2019

Bug fixes#

Restored the ability to import WebSocketProtocolError from websockets.

8.0#

July 7, 2019

Backwards-incompatible changes#

websockets 8.0 requires Python ≥ 3.6.

websockets 7.0 is the last version supporting Python 3.4 and 3.5.

process_request is now expected to be a coroutine.

If you’re passing a process_request argument to serve() or WebSocketServerProtocol, or if you’re overriding process_request() in a subclass, define it with async def instead of def. Previously, both were supported.

For backwards compatibility, functions are still accepted, but mixing functions and coroutines won’t work in some inheritance scenarios.

max_queue must be None to disable the limit.

If you were setting max_queue=0 to make the queue of incoming messages unbounded, change it to max_queue=None.

The host, port, and secure attributes of WebSocketCommonProtocol are deprecated.

Use local_address in servers and remote_address in clients instead of host and port.

WebSocketProtocolError is renamed to ProtocolError.

An alias provides backwards compatibility.

read_response() now returns the reason phrase.

If you’re using this low-level API, you must change your code.

New features#

Added basic_auth_protocol_factory() to enforce HTTP Basic Auth on the server side.
connect() handles redirects from the server during the handshake.
connect() supports overriding host and port.
Added unix_connect() for connecting to Unix sockets.
Added support for asynchronous generators in send() to generate fragmented messages incrementally.
Enabled readline in the interactive client.
Added type hints (PEP 484).
Added a FAQ to the documentation.
Added documentation for extensions.
Documented how to optimize memory usage.

Improvements#

send(), ping(), and pong() support bytes-like types bytearray and memoryview in addition to bytes.
Added ConnectionClosedOK and ConnectionClosedError subclasses of ConnectionClosed to tell apart normal connection termination from errors.
Changed WebSocketServer.close() to perform a proper closing handshake instead of failing the connection.
Improved error messages when HTTP parsing fails.
Improved API documentation.

Bug fixes#

Prevented spurious log messages about ConnectionClosed exceptions in keepalive ping task. If you were using ping_timeout=None as a workaround, you can remove it.
Avoided a crash when a extra_headers callable returns None.

7.0#

November 1, 2018

Backwards-incompatible changes#

Keepalive is enabled by default.

websockets now sends Ping frames at regular intervals and closes the connection if it doesn’t receive a matching Pong frame. See WebSocketCommonProtocol for details.

Termination of connections by WebSocketServer.close() changes.

Previously, connections handlers were canceled. Now, connections are closed with close code 1001 (going away).

From the perspective of the connection handler, this is the same as if the remote endpoint was disconnecting. This removes the need to prepare for CancelledError in connection handlers.

You can restore the previous behavior by adding the following line at the beginning of connection handlers:

def handler(websocket, path):
    closed = asyncio.ensure_future(websocket.wait_closed())
    closed.add_done_callback(lambda task: task.cancel())

Calling recv() concurrently raises a RuntimeError.

Concurrent calls lead to non-deterministic behavior because there are no guarantees about which coroutine will receive which message.

The timeout argument of serve() and connect() is renamed to close_timeout .

This prevents confusion with ping_timeout.

For backwards compatibility, timeout is still supported.

The origins argument of serve() changes.

Include None in the list rather than '' to allow requests that don’t contain an Origin header.

Pending pings aren’t canceled when the connection is closed.

A ping — as in ping = await websocket.ping() — for which no pong was received yet used to be canceled when the connection is closed, so that await ping raised CancelledError.

Now await ping raises ConnectionClosed like other public APIs.

New features#

Added process_request and select_subprotocol arguments to serve() and WebSocketServerProtocol to facilitate customization of process_request() and select_subprotocol().
Added support for sending fragmented messages.
Added the wait_closed() method to protocols.
Added an interactive client: python -m websockets <uri>.

Improvements#

Improved handling of multiple HTTP headers with the same name.
Improved error messages when a required HTTP header is missing.

Bug fixes#

Fixed a data loss bug in recv(): canceling it at the wrong time could result in messages being dropped.

6.0#

July 16, 2018

Backwards-incompatible changes#

The Headers class is introduced and several APIs are updated to use it.

The request_headers argument of process_request() is now a Headers instead of an http.client.HTTPMessage.
The request_headers and response_headers attributes of WebSocketCommonProtocol are now Headers instead of http.client.HTTPMessage.
The raw_request_headers and raw_response_headers attributes of WebSocketCommonProtocol are removed. Use raw_items() instead.
Functions defined in the handshake module now receive Headers in argument instead of get_header or set_header functions. This affects libraries that rely on low-level APIs.
Functions defined in the http module now return HTTP headers as Headers instead of lists of (name, value) pairs.

Since Headers and http.client.HTTPMessage provide similar APIs, much of the code dealing with HTTP headers won’t require changes.

New features#

Added compatibility with Python 3.7.

5.0.1#

May 24, 2018

Bug fixes#

Fixed a regression in 5.0 that broke some invocations of serve() and connect().

5.0#

May 22, 2018

Security fix#

websockets 5.0 fixes a security issue introduced in 4.0.

Version 4.0 was vulnerable to denial of service by memory exhaustion because it didn’t enforce max_size when decompressing compressed messages (CVE-2018-1000518).

Backwards-incompatible changes#

A user_info field is added to the return value of parse_uri and WebSocketURI.

If you’re unpacking WebSocketURI into four variables, adjust your code to account for that fifth field.

New features#

connect() performs HTTP Basic Auth when the URI contains credentials.
unix_serve() can be used as an asynchronous context manager on Python ≥ 3.5.1.
Added the closed property to protocols.
Added new examples in the documentation.

Improvements#

Iterating on incoming messages no longer raises an exception when the connection terminates with close code 1001 (going away).
A plain HTTP request now receives a 426 Upgrade Required response and doesn’t log a stack trace.
If a ping() doesn’t receive a pong, it’s canceled when the connection is closed.
Reported the cause of ConnectionClosed exceptions.
Stopped logging stack traces when the TCP connection dies prematurely.
Prevented writing to a closing TCP connection during unclean shutdowns.
Made connection termination more robust to network congestion.
Prevented processing of incoming frames after failing the connection.
Updated documentation with new features from Python 3.6.
Improved several sections of the documentation.

Bug fixes#

Prevented TypeError due to missing close code on connection close.
Fixed a race condition in the closing handshake that raised InvalidState.

4.0.1#

November 2, 2017

Bug fixes#

Fixed issues with the packaging of the 4.0 release.

4.0#

November 2, 2017

Backwards-incompatible changes#

websockets 4.0 requires Python ≥ 3.4.

websockets 3.4 is the last version supporting Python 3.3.

Compression is enabled by default.

In August 2017, Firefox and Chrome support the permessage-deflate extension, but not Safari and IE.

Compression should improve performance but it increases RAM and CPU use.

If you want to disable compression, add compression=None when calling serve() or connect().

The state_name attribute of protocols is deprecated.

Use protocol.state.name instead of protocol.state_name.

New features#

WebSocketCommonProtocol instances can be used as asynchronous iterators on Python ≥ 3.6. They yield incoming messages.
Added unix_serve() for listening on Unix sockets.
Added the sockets attribute to the return value of serve().
Allowed extra_headers to override Server and User-Agent headers.

Improvements#

Reorganized and extended documentation.
Rewrote connection termination to increase robustness in edge cases.
Reduced verbosity of “Failing the WebSocket connection” logs.

Bug fixes#

Aborted connections if they don’t close within the configured timeout.
Stopped leaking pending tasks when cancel() is called on a connection while it’s being closed.

3.4#

August 20, 2017

Backwards-incompatible changes#

InvalidStatus is replaced by InvalidStatusCode.

This exception is raised when connect() receives an invalid response status code from the server.

New features#

serve() can be used as an asynchronous context manager on Python ≥ 3.5.1.
Added support for customizing handling of incoming connections with process_request().
Made read and write buffer sizes configurable.

Improvements#

Renamed serve() and connect()’s klass argument to create_protocol to reflect that it can also be a callable. For backwards compatibility, klass is still supported.
Rewrote HTTP handling for simplicity and performance.
Added an optional C extension to speed up low-level operations.

Bug fixes#

Providing a sock argument to connect() no longer crashes.

3.3#

March 29, 2017

New features#

Ensured compatibility with Python 3.6.

Improvements#

Reduced noise in logs caused by connection resets.

Bug fixes#

Avoided crashing on concurrent writes on slow connections.

3.2#

August 17, 2016

New features#

Added timeout, max_size, and max_queue arguments to connect() and serve().

Improvements#

Made server shutdown more robust.

3.1#

April 21, 2016

New features#

Added flow control for incoming data.

Bug fixes#

Avoided a warning when closing a connection before the opening handshake.

3.0#

December 25, 2015

Backwards-incompatible changes#

recv() now raises an exception when the connection is closed.

recv() used to return None when the connection was closed. This required checking the return value of every call:

message = await websocket.recv()
if message is None:
    return

Now it raises a ConnectionClosed exception instead. This is more Pythonic. The previous code can be simplified to:

message = await websocket.recv()

When implementing a server, there’s no strong reason to handle such exceptions. Let them bubble up, terminate the handler coroutine, and the server will simply ignore them.

In order to avoid stranding projects built upon an earlier version, the previous behavior can be restored by passing legacy_recv=True to serve(), connect(), WebSocketServerProtocol, or WebSocketClientProtocol.

New features#

connect() can be used as an asynchronous context manager on Python ≥ 3.5.1.
ping() and pong() support data passed as str in addition to bytes.
Made state_name attribute on protocols a public API.

Improvements#

Updated documentation with await and async syntax from Python 3.5.
Worked around an asyncio bug affecting connection termination under load.
Improved documentation.

2.7#

November 18, 2015

New features#

Added compatibility with Python 3.5.

Improvements#

Refreshed documentation.

2.6#

August 18, 2015

New features#

Added local_address and remote_address attributes on protocols.
Closed open connections with code 1001 when a server shuts down.

Bug fixes#

Avoided TCP fragmentation of small frames.

2.5#

July 28, 2015

New features#

Provided access to handshake request and response HTTP headers.
Allowed customizing handshake request and response HTTP headers.
Added support for running on a non-default event loop.

Improvements#

Improved documentation.
Sent a 403 status code instead of 400 when request Origin isn’t allowed.
Clarified that the closing handshake can be initiated by the client.
Set the close code and reason more consistently.
Strengthened connection termination.

Bug fixes#

Canceling recv() no longer drops the next message.

2.4#

January 31, 2015

New features#

Added support for subprotocols.
Added loop argument to connect() and serve().

2.3#

November 3, 2014

Improvements#

Improved compliance of close codes.

2.2#

July 28, 2014

New features#

Added support for limiting message size.

2.1#

April 26, 2014

New features#

Added host, port and secure attributes on protocols.
Added support for providing and checking Origin.

2.0#

February 16, 2014

Backwards-incompatible changes#

send(), ping(), and pong() are now coroutines.

They used to be functions.

Instead of:

websocket.send(message)

you must write:

await websocket.send(message)

New features#

Added flow control for outgoing data.

1.0#

November 14, 2013

New features#

Initial public release.