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 APIs are considered private. They may change at any time.
November 14, 2021
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
pathattribute 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 ...
python -m websockets --version.
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.
Improved performance for large messages on ARM processors.
Documented how to auto-reload on code changes in development.
Avoided half-closing TCP connections that are already closed.
September 9, 2021
websockets 10.0 requires Python ≥ 3.7.
websockets 9.1 is the last version supporting Python 3.6.
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.
loop parameter is also removed
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.
legacy_recv option is deprecated.
See the release notes of websockets 3.0 for details.
The signature of
If you raise
ConnectionClosed or a subclass, rather
than catch them when websockets raises them, you must change your code.
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.
broadcast()to send a message to many clients.
Added support for reconnecting automatically by using
connect()as an asynchronous iterator.
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.
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
Handled TCP connection drops during the opening handshake.
Made it easier to customize authentication with
Provided additional information in
Clarified several exceptions or log messages.
Improved API documentation.
Avoided a crash when receiving a ping while the connection is closing.
May 27, 2021
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).
May 15, 2021
Restored compatibility of
python -m websocketswith Python < 3.9.
Restored compatibility with mypy.
May 2, 2021
Fixed issues with the packaging of the 9.0 release.
May 1, 2021
Several modules are moved or deprecated.
Aliases provide compatibility for all previously public APIs according to the backwards-compatibility policy
authmodules were moved from the
websocketspackage to a
websockets.legacysub-package. Despite the name, they’re still fully supported.
urimodules in the
websocketspackage 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, static code analysis tools such as mypy are unable to understand the behavior.
If you depend on such tools, use the real import path, which can be found in the API documentation, for example:
from websockets.client import connect from websockets.server import serve
Added compatibility with Python 3.9.
Fixed sending fragmented, compressed messages.
Hostheader 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.
November 1, 2019
Added compatibility with Python 3.8.
July 31, 2019
Restored the ability to pass a socket with the
Removed an incorrect assertion when a connection drops.
July 21, 2019
Restored the ability to import
July 7, 2019
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
WebSocketServerProtocol, or if
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
WebSocketCommonProtocol are deprecated.
WebSocketProtocolError is renamed
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.
basic_auth_protocol_factory()to enforce HTTP Basic Auth on the server side.
connect()handles redirects from the server during the handshake.
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.
WebSocketServer.close()to perform a proper closing handshake instead of failing the connection.
Improved error messages when HTTP parsing fails.
Improved API documentation.
November 1, 2018
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.
WebSocketCommonProtocol for details.
Termination of connections by
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())
Concurrent calls lead to non-deterministic behavior because there are no guarantees about which coroutine will receive which message.
This prevents confusion with
For backwards compatibility,
timeout is still supported.
origins argument of
None in the list rather than
'' to allow requests that
don’t contain an Origin header.
Added support for sending fragmented messages.
wait_closed()method to protocols.
Added an interactive client:
python -m websockets <uri>.
Improved handling of multiple HTTP headers with the same name.
Improved error messages when a required HTTP header is missing.
Fixed a data loss bug in
recv(): canceling it at the wrong time could result in messages being dropped.
July 16, 2018
Headers class is introduced and
several APIs are updated to use it.
Functions defined in the
handshakemodule now receive
Headersin argument instead of
set_headerfunctions. This affects libraries that rely on low-level APIs.
Functions defined in the
httpmodule now return HTTP headers as
Headersinstead of lists of
provide similar APIs, much of the code dealing with HTTP headers won’t
Added compatibility with Python 3.7.
May 24, 2018
May 22, 2018
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
user_info field is added to the return value of
If you’re unpacking
WebSocketURI into four variables, adjust your code
to account for that fifth field.
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.
ping()doesn’t receive a pong, it’s canceled when the connection is closed.
Reported the cause of
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.
November 2, 2017
Fixed issues with the packaging of the 4.0 release.
November 2, 2017
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.
state_name attribute of protocols is deprecated.
protocol.state.name instead of
Reorganized and extended documentation.
Rewrote connection termination to increase robustness in edge cases.
Reduced verbosity of “Failing the WebSocket connection” logs.
Aborted connections if they don’t close within the configured
Stopped leaking pending tasks when
cancel()is called on a connection while it’s being closed.
August 20, 2017
connect()no longer crashes.
March 29, 2017
Ensured compatibility with Python 3.6.
Reduced noise in logs caused by connection resets.
Avoided crashing on concurrent writes on slow connections.
August 17, 2016
Made server shutdown more robust.
April 21, 2016
Added flow control for incoming data.
Avoided a warning when closing a connection before the opening handshake.
December 25, 2015
raises an exception when the connection is closed.
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
Updated documentation with
asyncsyntax from Python 3.5.
Worked around an
asynciobug affecting connection termination under load.
November 18, 2015
Added compatibility with Python 3.5.
August 18, 2015
remote_addressattributes on protocols.
Closed open connections with code 1001 when a server shuts down.
Avoided TCP fragmentation of small frames.
July 28, 2015
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.
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.
recv()no longer drops the next message.
January 31, 2015
November 3, 2014
Improved compliance of close codes.
July 28, 2014
Added support for limiting message size.
April 26, 2014
secureattributes on protocols.
Added support for providing and checking Origin.
February 16, 2014
Added flow control for outgoing data.
November 14, 2013
Initial public release.