NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #68 most downloaded on PyPI
An implementation of the WebSocket Protocol (RFC 6455 & 7692)
Last release today
03 Oct 2026
Ships unpredictably
gaps range from 8 days to 10 months
Nearly every release is documented
notes for 53 of 54 stable releases
Nothing withdrawn
no release was ever pulled
13 years old
54 releases · first in 2013
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
October 3, 2026
Added wait_closed() to the threading implementation.
connect() now closes connections with close code 1011 (internal error) when exiting the context manager with an exception.
Improved error handling when a compression window of size 8 is requested.
Fixed handling of percent-encoded credentials in WebSocket and proxy URIs.
Fixed a regression from 16.1 where the legacy implementation rejected non-ASCII headers.
October 3, 2026
Added ~sync.connection.Connection.wait_closed to the threading implementation.
~asyncio.client.connect now closes connections with close code 1011 (internal error) when exiting the context manager with an exception.
Improved error handling when a compression window of size 8 is requested.
Fixed handling of percent-encoded credentials in WebSocket and proxy URIs.
Fixed a regression from 16.1 where the legacy implementation rejected non-ASCII headers.
One column per quarter.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
August 26, 2026
Added support for reconnecting automatically by using reconnect() as an iterator to the threading implementation.
connect() now follows redirects in the threading implementation.
connect() can connect to another host and port than those specified in the URI in the threading implementation.
Connections are now garbage collected immediately once closed.
unix_connect() and unix_serve() now accept path-like objects, such as pathlib.Path , in the path argument.
August 26, 2026
Added support for reconnecting automatically by using ~sync.client.reconnect as an iterator to the threading implementation.
~sync.client.connect now follows redirects in the threading implementation.
~sync.client.connect can connect to another host and port than those specified in the URI in the threading implementation.
Connections are now garbage collected immediately once closed.
~sync.client.unix_connect and ~sync.server.unix_serve now accept path-like objects, such as pathlib.Path, in the path argument.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
July 31, 2026
Restored compatibility of serve_forever() in the asyncio implementation with third-party event loops such as uvloop .
Prevented the Trio implementation from crashing when backpressure kicks in, i.e. when receiving data faster than the application can process it.
July 31, 2026
Restored compatibility of ~asyncio.server.Server.serve_forever in the asyncio implementation with third-party event loops such as uvloop.
Prevented the Trio implementation from crashing when backpressure kicks in, i.e. when receiving data faster than the application can process it.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
July 29, 2026
websockets 17.0 requires Python ≥ 3.11.
websockets 16.1 is the last version supporting Python 3.10.
Aliases for modules moved or deprecated in 9.0 are removed.
See the changelog of version 9.0 for details.
process_request may receive requests using an HTTP method other than GET or using the HTTP/1.0 protocol.
Previously, the server closed the connection without returning an HTTP response. Now, process_request runs and can return an HTTP response.
Several boolean arguments are now keyword-only.
If you were passing some of the following as positional arguments, you must update your code to pass them as keyword arguments.
send(text=...)
ping(ack_on_close=...)
broadcast(raise_exceptions=...)
Encoding and decoding non-ASCII headers in handshake requests and responses changed.
The previous behavior was undocumented, inconsistent, and didn’t match the HTTP specification. If you relied on the encoding being UTF-8 or ASCII with surrogate escapes, depending on the context, you must switch to ISO-8859-1.
In the threading implementation, the socket argument is renamed to sock .
The first argument of ClientConnection and ServerConnection is renamed from socket to sock for consistency with connect() and serve() . The first argument of Server is also renamed. If you’re passing it as a keyword argument, you must change your code.
websockets 17.0 introduces a trio implementation.
It is an alternative to the asyncio implementation.
See websockets.trio.client.connect() and websockets.trio.server.serve() for details.
Validated compatibility with Python 3.15.
Added broadcast() to the threading implementation.
Made the set of active connections available in the Server.connections property in the threading implementation.
Closed connections when shutting down the server in the threading implementation. See shutdown() for details.
Added the --insecure option to the websockets CLI to disable TLS certificate validation.
Supported non-ASCII headers consistently in handshake requests and responses, using ISO-8859-1 encoding.
Replied with HTTP 405 Method Not Allowed when the handshake request doesn’t use the GET method, and with HTTP 505 HTTP Version Not Supported when it doesn’t use HTTP/1.1, instead of closing the connection.
Replied with HTTP 414 URI Too Long or 431 Request Header Fields Too Large when the handshake request exceeds a security limit, instead of closing the connection.
Reduced noise in server logs when clients fail to establish a connection.
Clarified logs when process_request sends a plain HTTP response, without attempting to open a WebSocket connection.
Added the reconnect_delays argument for customizing the delays between reconnection attempts in connect() , beyond existing WEBSOCKETS_BACKOFF_* environment variables.
Added wheels for Windows ARM64 and Linux i686.
Restored compatibility of the websockets CLI with Windows.
Fixed serve_forever() in the asyncio implementation so that canceling it always closes connections gracefully.
Fixed a bug that could delay or block the client in the threading implementation on macOS when the opening handshake fails.
July 29, 2026
websockets 17.0 requires Python ≥ 3.11.
websockets 16.1 is the last version supporting Python 3.10.
Aliases for modules moved or deprecated in 9.0 are removed.
See the changelog of version 9.0 for details.
process_request may receive requests using an HTTP method other than GET or using the HTTP/1.0 protocol.
Previously, the server closed the connection without returning an HTTP response. Now, process_request runs and can return an HTTP response.
Several boolean arguments are now keyword-only.
If you were passing some of the following as positional arguments, you must update your code to pass them as keyword arguments.
send(text=...)
ping(ack_on_close=...)
broadcast(raise_exceptions=...)
Encoding and decoding non-ASCII headers in handshake requests and responses changed.
The previous behavior was undocumented, inconsistent, and didn't match the HTTP specification. If you relied on the encoding being UTF-8 or ASCII with surrogate escapes, depending on the context, you must switch to ISO-8859-1.
In the threading implementation, the socket argument is renamed to sock.
The first argument of ~sync.client.ClientConnection and ~sync.server.ServerConnection is renamed from socket to sock for consistency with ~sync.client.connect and ~sync.server.serve. The first argument of ~sync.server.Server is also renamed. If you're passing it as a keyword argument, you must change your code.
websockets 17.0 introduces a trio implementation.
It is an alternative to the asyncio implementation.
See websockets.trio.client.connect and websockets.trio.server.serve for details.
Validated compatibility with Python 3.15.
Added ~sync.server.broadcast to the threading implementation.
Made the set of active connections available in the Server.connections property in the threading implementation.
Closed connections when shutting down the server in the threading implementation. See ~sync.server.Server.shutdown for details.
Added the --insecure option to the websockets CLI to disable TLS certificate validation.
Supported non-ASCII headers consistently in handshake requests and responses, using ISO-8859-1 encoding.
Replied with HTTP 405 Method Not Allowed when the handshake request doesn't use the GET method, and with HTTP 505 HTTP Version Not Supported when it doesn't use HTTP/1.1, instead of closing the connection.
Replied with HTTP 414 URI Too Long or 431 Request Header Fields Too Large when the handshake request exceeds a security limit, instead of closing the connection.
Reduced noise in server logs when clients fail to establish a connection.
Clarified logs when process_request sends a plain HTTP response, without attempting to open a WebSocket connection.
Added the reconnect_delays argument for customizing the delays between reconnection attempts in ~asyncio.client.connect, beyond existing WEBSOCKETS_BACKOFF_* environment variables.
Added wheels for Windows ARM64 and Linux i686.
Restored compatibility of the websockets CLI with Windows.
Fixed ~asyncio.server.Server.serve_forever in the asyncio implementation so that canceling it always closes connections gracefully.
Fixed a bug that could delay or block the client in the threading implementation on macOS when the opening handshake fails.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
July 18, 2026
Reverted a backwards-incompatible change in decoding non-ASCII header values.
July 18, 2026
Reverted a backwards-incompatible change in decoding non-ASCII header values.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
July 9, 2026
Added an option to force broadcast() to send bytes in text frames, or str in binary frames.
Stripped Authorization , Cookie , and Proxy-Authorization headers when clients follow cross-origin redirects, a security hardening measure.
Escaped control characters in incoming messages in the websockets CLI.
Prevented setting invalid header values in Headers .
Rejected incorrect fragmented, compressed messages.
Added wheels for ARMv7, PowerPC, RISC-V, and S/390.
Prevented str(frame) from crashing when a text frame is fragmented in the middle of a UTF-8 sequence.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
January 10, 2026
websockets 16.0 requires Python ≥ 3.10.
websockets 15.0 is the last version supporting Python 3.9.
Validated compatibility with Python 3.14.
Added support for free-threaded Python.
Allowed setting separate limits for messages and fragments with max_size .
Added support for HTTP/1.0 proxies.
Added support for customizing the close code and reason for connections in Server.close .
Prevented recv() from returning bytearray instead of bytes in edge cases.
Fixed a race condition that could lead to an exception when closing connections in the threading implementation.
January 10, 2026
websockets 16.0 requires Python ≥ 3.10.
websockets 15.0 is the last version supporting Python 3.9.
Validated compatibility with Python 3.14.
Added support for free-threaded Python.
Allowed setting separate limits for messages and fragments with max_size.
Added support for HTTP/1.0 proxies.
Added support for customizing the close code and reason for connections in Server.close.
Prevented ~asyncio.connection.Connection.recv from returning bytearray instead of bytes in edge cases.
Fixed a race condition that could lead to an exception when closing connections in the threading implementation.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
March 5, 2025
Added an entry point for running the CLI as websockets .
Prevented an exception when exiting the CLI.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
February 16, 2025
Client connections use SOCKS and HTTP proxies automatically.
If a proxy is configured in the operating system or with an environment variable, websockets uses it automatically when connecting to a server. SOCKS proxies require installing the third-party library python-socks .
If you want to disable the proxy, add proxy=None when calling connect() .
See proxies for details.
Keepalive is enabled in the threading implementation.
The threading implementation now sends Ping frames at regular intervals and closes the connection if it doesn’t receive a matching Pong frame just like the asyncio implementation.
See keepalive and latency for details.
Added route() and unix_route() to dispatch connections to handlers based on the request path. Read more about routing in routing .
Refreshed several how-to guides and topic guides.
Added type overloads for the decode argument of recv() . This may simplify static typing.
February 16, 2025
Client connections use SOCKS and HTTP proxies automatically.
If a proxy is configured in the operating system or with an environment variable, websockets uses it automatically when connecting to a server. SOCKS proxies require installing the third-party library python-socks.
If you want to disable the proxy, add proxy=None when calling ~asyncio.client.connect.
See proxies for details.
Keepalive is enabled in the threading implementation.
The threading implementation now sends Ping frames at regular intervals and closes the connection if it doesn't receive a matching Pong frame just like the asyncio implementation.
See keepalive and latency for details.
Added ~asyncio.router.route and ~asyncio.router.unix_route to dispatch connections to handlers based on the request path. Read more about routing in routing.
Refreshed several how-to guides and topic guides.
Added type overloads for the decode argument of ~asyncio.connection.Connection.recv. This may simplify static typing.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
January 19, 2025
Added support for regular expressions in the origins argument of serve() .
Wrapped errors when reading the opening handshake request or response in InvalidMessage so that connect() raises InvalidHandshake or a subclass when the opening handshake fails.
Fixed recv() with timeout=0 in the threading implementation. If a message is already received, it is returned. Previously, TimeoutError was raised incorrectly.
Fixed a crash in the asyncio implementation when canceling a ping then receiving the corresponding pong.
Prevented close() from blocking when the network becomes unavailable or when receive buffers are saturated in the asyncio and threading implementations.
January 19, 2025
Added support for regular expressions in the origins argument of ~asyncio.server.serve.
Wrapped errors when reading the opening handshake request or response in ~exceptions.InvalidMessage so that ~asyncio.client.connect raises ~exceptions.InvalidHandshake or a subclass when the opening handshake fails.
Fixed ~sync.connection.Connection.recv with timeout=0 in the threading implementation. If a message is already received, it is returned. Previously, TimeoutError was raised incorrectly.
Fixed a crash in the asyncio implementation when canceling a ping then receiving the corresponding pong.
Prevented ~asyncio.connection.Connection.close from blocking when the network becomes unavailable or when receive buffers are saturated in the asyncio and threading implementations.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
November 13, 2024
Supported max_queue=None in the asyncio and threading implementations for consistency with the legacy implementation, even though this is never a good idea.
Added close_code and close_reason attributes in the asyncio and threading implementations for consistency with the legacy implementation.
Once the connection is closed, messages previously received and buffered can be read in the asyncio and threading implementations, just like in the legacy implementation.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
November 9, 2024
websockets 14.0 requires Python ≥ 3.9.
websockets 13.1 is the last version supporting Python 3.8.
The new asyncio implementation is now the default.
The following aliases in the websockets package were switched to the new asyncio implementation:
from websockets import connect , unix_connext from websockets import broadcast , serve , unix_serve
If you’re using any of them, then you must follow the upgrade guide immediately.
Alternatively, you may stick to the legacy asyncio implementation for now by importing it explicitly:
from websockets.legacy.client import connect , unix_connect from websockets.legacy.server import broadcast , serve , unix_serve
The legacy asyncio implementation is now deprecated.
The upgrade guide provides complete instructions to migrate your application.
Aliases for deprecated API were removed from websockets.all , meaning that they cannot be imported with from websockets import * anymore.
Several API raise ValueError instead of TypeError on invalid arguments.
connect() , unix_connect() , and basic_auth() in the asyncio implementation as well as connect() , unix_connect() , serve() , unix_serve() , and basic_auth() in the threading implementation now raise ValueError when a required argument isn’t provided or an argument that is incompatible with others is provided.
Frame.data is now a bytes-like object.
In addition to bytes , it may be a bytearray or a memoryview . If you wrote an Extension that relies on methods not provided by these types, you must update your code.
The signature of PayloadTooBig changed.
If you wrote an extension that raises PayloadTooBig in decode() , for example, you must replace PayloadTooBig(f"over size limit ({size} > {max_size} bytes)") with PayloadTooBig(size, max_size) .
Added an option to receive text frames as bytes , without decoding, in the threading implementation; also binary frames as str .
Added an option to send bytes in a text frame in the asyncio and threading implementations; also str in a binary frame.
The threading implementation receives messages faster.
Sending or receiving large compressed messages is now faster.
Errors when a fragmented message is too large are clearer.
Log messages at the WARNING and INFO levels no longer include stack traces.
Clients no longer crash when the server rejects the opening handshake and the HTTP response doesn’t Include a Content-Length header.
Returning an HTTP response in process_request or process_response doesn’t generate a log message at the ERROR level anymore.
Connections are closed with code 1007 (invalid data) when receiving invalid UTF-8 in a text frame.
November 9, 2024
websockets 14.0 requires Python ≥ 3.9.
websockets 13.1 is the last version supporting Python 3.8.
The new asyncio implementation is now the default.
The following aliases in the websockets package were switched to the new asyncio implementation:
from websockets import connect, unix_connext from websockets import broadcast, serve, unix_serve
If you're using any of them, then you must follow the upgrade guide immediately.
Alternatively, you may stick to the legacy asyncio implementation for now by importing it explicitly:
from websockets.legacy.client import connect, unix_connect from websockets.legacy.server import broadcast, serve, unix_serve
The legacy asyncio implementation is now deprecated.
The upgrade guide provides complete instructions to migrate your application.
Aliases for deprecated API were removed from websockets.__all__, meaning that they cannot be imported with from websockets import * anymore.
Several API raise ValueError instead of TypeError on invalid arguments.
~asyncio.client.connect, ~asyncio.client.unix_connect, and ~asyncio.server.basic_auth in the asyncio implementation as well as ~sync.client.connect, ~sync.client.unix_connect, ~sync.server.serve, ~sync.server.unix_serve, and ~sync.server.basic_auth in the threading implementation now raise ValueError when a required argument isn't provided or an argument that is incompatible with others is provided.
Frame.data is now a bytes-like object.
In addition to bytes, it may be a bytearray or a memoryview. If you wrote an ~extensions.Extension that relies on methods not provided by these types, you must update your code.
The signature of ~exceptions.PayloadTooBig changed.
If you wrote an extension that raises ~exceptions.PayloadTooBig in ~extensions.Extension.decode, for example, you must replace PayloadTooBig(f"over size limit ({size} > {max_size} bytes)") with PayloadTooBig(size, max_size).
Added an option to receive text frames as bytes, without decoding, in the threading implementation; also binary frames as str.
Added an option to send bytes in a text frame in the asyncio and threading implementations; also str in a binary frame.
The threading implementation receives messages faster.
Sending or receiving large compressed messages is now faster.
Errors when a fragmented message is too large are clearer.
Log messages at the ~logging.WARNING and ~logging.INFO levels no longer include stack traces.
Clients no longer crash when the server rejects the opening handshake and the HTTP response doesn't Include a Content-Length header.
Returning an HTTP response in process_request or process_response doesn't generate a log message at the ~logging.ERROR level anymore.
Connections are closed with code 1007 (invalid data) when receiving invalid UTF-8 in a text frame.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
September 21, 2024
The code and reason attributes of ConnectionClosed are deprecated.
They were removed from the documentation in version 10.0, due to their spec-compliant but counter-intuitive behavior, but they were kept in the code for backwards compatibility. They’re now formally deprecated.
Added support for reconnecting automatically by using connect() as an asynchronous iterator to the new asyncio implementation.
connect() now follows redirects in the new asyncio implementation.
Added HTTP Basic Auth to the asyncio and threading implementations of servers.
Made the set of active connections available in the Server.connections property.
Improved reporting of errors during the opening handshake.
Raised ConcurrencyError on unsupported concurrent calls. Previously, RuntimeError was raised. For backwards compatibility, ConcurrencyError is a subclass of RuntimeError .
The asyncio and threading implementations of servers don’t start the connection handler anymore when process_request or process_response returns an HTTP response.
Fixed a bug in the threading implementation that could lead to incorrect error reporting when closing a connection while recv() is running.
September 21, 2024
The code and reason attributes of ~exceptions.ConnectionClosed are deprecated.
They were removed from the documentation in version 10.0, due to their spec-compliant but counter-intuitive behavior, but they were kept in the code for backwards compatibility. They're now formally deprecated.
Added support for reconnecting automatically by using ~asyncio.client.connect as an asynchronous iterator to the new asyncio implementation.
~asyncio.client.connect now follows redirects in the new asyncio implementation.
Added HTTP Basic Auth to the asyncio and threading implementations of servers.
Made the set of active connections available in the Server.connections property.
Improved reporting of errors during the opening handshake.
Raised ~exceptions.ConcurrencyError on unsupported concurrent calls. Previously, RuntimeError was raised. For backwards compatibility, ~exceptions.ConcurrencyError is a subclass of RuntimeError.
The asyncio and threading implementations of servers don't start the connection handler anymore when process_request or process_response returns an HTTP response.
Fixed a bug in the threading implementation that could lead to incorrect error reporting when closing a connection while ~sync.connection.Connection.recv is running.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
August 28, 2024
Restored the C extension in the source distribution.
August 28, 2024
Restored the C extension in the source distribution.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
August 20, 2024
Receiving the request path in the second parameter of connection handlers is deprecated.
If you implemented the connection handler of a server as:
async def handler ( request , path ): ...
You should switch to the pattern recommended since version 10.1:
async def handler ( request ): path = request . path # only if handler() uses the path argument ...
The ssl_context argument of connect() and serve() in the threading implementation is renamed to ssl .
This aligns the API of the threading implementation with the asyncio implementation.
For backwards compatibility, ssl_context is still supported.
The WebSocketServer class in the threading implementation is renamed to Server .
This change should be transparent because this class shouldn’t be instantiated directly; serve() returns an instance.
Regardless, an alias provides backwards compatibility.
websockets 13.0 introduces a new asyncio implementation.
This new implementation is intended to be a drop-in replacement for the current implementation. It will become the default in a future release.
Please try it and report any issue that you encounter! The upgrade guide explains everything you need to know about the upgrade process.
Validated compatibility with Python 3.12 and 3.13.
Added an option to receive text frames as bytes , without decoding, in the asyncio implementation; also binary frames as str .
Added environment variables to configure debug logs, the Server and User-Agent headers, as well as security limits.
If you were monkey-patching constants, be aware that they were renamed, which will break your configuration. You must switch to the environment variables.
The error message in server logs when a header is too long is more explicit.
Fixed a bug in the threading implementation that could prevent the program from exiting when a connection wasn’t closed properly.
Redirecting from a ws:// URI to a wss:// URI now works.
broadcast(raise_exceptions=True) no longer crashes when there isn’t any exception.
August 20, 2024
Receiving the request path in the second parameter of connection handlers is deprecated.
If you implemented the connection handler of a server as:
async def handler(request, path): ...
You should switch to the pattern recommended since version 10.1:
async def handler(request):
path = request.path # only if handler() uses the path argument
...
The ssl_context argument of ~sync.client.connect and ~sync.server.serve in the threading implementation is renamed to ssl.
This aligns the API of the threading implementation with the asyncio implementation.
For backwards compatibility, ssl_context is still supported.
The WebSocketServer class in the threading implementation is renamed to ~sync.server.Server.
This change should be transparent because this class shouldn't be instantiated directly; ~sync.server.serve returns an instance.
Regardless, an alias provides backwards compatibility.
websockets 13.0 introduces a new asyncio implementation.
This new implementation is intended to be a drop-in replacement for the current implementation. It will become the default in a future release.
Please try it and report any issue that you encounter! The upgrade guide explains everything you need to know about the upgrade process.
Validated compatibility with Python 3.12 and 3.13.
Added an option to receive text frames as bytes, without decoding, in the asyncio implementation; also binary frames as str.
Added environment variables to configure debug logs, the Server and User-Agent headers, as well as security limits.
If you were monkey-patching constants, be aware that they were renamed, which will break your configuration. You must switch to the environment variables.
The error message in server logs when a header is too long is more explicit.
Fixed a bug in the threading implementation that could prevent the program from exiting when a connection wasn't closed properly.
Redirecting from a ws:// URI to a wss:// URI now works.
broadcast(raise_exceptions=True) no longer crashes when there isn't any exception.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
October 21, 2023
websockets 12.0 requires Python ≥ 3.8.
websockets 11.0 is the last version supporting Python 3.7.
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 .
October 21, 2023
websockets 12.0 requires Python ≥ 3.8.
websockets 11.0 is the last version supporting Python 3.7.
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 ~http.HTTPStatus is expected.
Added ~frames.CloseCode.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
May 7, 2023
Fixed the threading implementation of servers on Windows.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
April 18, 2023
Fixed a deadlock in the threading implementation when closing a connection without reading all messages.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
April 6, 2023
Restored the C extension in the source distribution.
April 6, 2023
Restored the C extension in the source distribution.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
April 2, 2023
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.
websockets 11.0 introduces a threading implementation.
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 websockets.sync.client.connect() and websockets.sync.server.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.
Added platform-independent wheels.
Improved error handling in broadcast() .
Set server_hostname automatically on TLS connections when providing a sock argument to connect() .
April 2, 2023
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 ~server.ServerProtocol or ~client.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 ~exceptions.ConnectionClosedOK instead of ~exceptions.ConnectionClosedError.
As a consequence, calling WebSocket.close() without arguments in a browser isn't reported as an error anymore.
~legacy.server.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.
websockets 11.0 introduces a threading implementation.
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 websockets.sync.client.connect and websockets.sync.server.serve for details.
Added open_timeout to ~legacy.server.serve.
Made it possible to close a server without closing existing connections.
Added ~server.ServerProtocol.select_subprotocol to customize negotiation of subprotocols in the Sans-I/O layer.
Added platform-independent wheels.
Improved error handling in ~legacy.server.broadcast.
Set server_hostname automatically on TLS connections when providing a sock argument to ~sync.client.connect.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
October 25, 2022
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.
Improved FAQ.
October 25, 2022
Validated compatibility with Python 3.11.
Added the ~legacy.protocol.WebSocketCommonProtocol.latency property to protocols.
Changed ~legacy.protocol.WebSocketCommonProtocol.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.
Improved FAQ.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
April 17, 2022
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.
Reduced noise in logs when ssl or zlib raise exceptions.
April 17, 2022
The exception attribute of ~http11.Request and ~http11.Response is deprecated.
Use the handshake_exc attribute of ~server.ServerProtocol and ~client.ClientProtocol instead.
See ../howto/sansio for details.
Reduced noise in logs when ssl or zlib raise exceptions.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
February 21, 2022
Made compression negotiation more lax for compatibility with Firefox.
Improved FAQ and quick start guide.
Fixed backwards-incompatibility in 10.1 for connection handlers created with functools.partial() .
Avoided leaking open sockets when connect() is canceled.
February 21, 2022
Made compression negotiation more lax for compatibility with Firefox.
Improved FAQ and quick start guide.
Fixed backwards-incompatibility in 10.1 for connection handlers created with functools.partial.
Avoided leaking open sockets when ~legacy.client.connect is canceled.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
November 14, 2021
Added a tutorial.
Made the second parameter of connection handlers optional. 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 with:
async def handler ( request ): path = request . path # only if handler() uses the path argument ...
Added 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 .
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.
Avoided half-closing TCP connections that are already closed.
November 14, 2021
Added a tutorial.
Made the second parameter of connection handlers optional. The request path is available in the ~legacy.protocol.WebSocketCommonProtocol.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 with:
async def handler(request):
path = request.path # only if handler() uses the path argument
...
Added 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.
Mirrored the entire ~asyncio.Server API in ~legacy.server.WebSocketServer.
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.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
September 9, 2021
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.
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.
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.
Avoided a crash when receiving a ping while the connection is closing.
September 9, 2021
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 ~legacy.server.WebSocketServer. This should be transparent.
~legacy.client.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 ~exceptions.ConnectionClosed changed.
If you raise ~exceptions.ConnectionClosed or a subclass, rather than catch them when websockets raises them, you must change your code.
A msg parameter was added to ~exceptions.InvalidURI.
If you raise ~exceptions.InvalidURI, rather than catch it when websockets raises it, 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.
Added ~legacy.server.broadcast to send a message to many clients.
Added support for reconnecting automatically by using ~legacy.client.connect as an asynchronous iterator.
Added open_timeout to ~legacy.client.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.
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 ~legacy.client.connect.
Handled TCP connection drops during the opening handshake.
Made it easier to customize authentication with ~legacy.auth.BasicAuthWebSocketServerProtocol.check_credentials.
Provided additional information in ~exceptions.ConnectionClosed exceptions.
Clarified several exceptions or log messages.
Restructured documentation.
Improved API documentation.
Extended FAQ.
Avoided a crash when receiving a ping while the connection is closing.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
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 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).
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
May 15, 2021
Restored compatibility of python -m websockets with Python < 3.9.
Restored compatibility with mypy.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
May 2, 2021
Fixed issues with the packaging of the 9.0 release.
May 2, 2021
Fixed issues with the packaging of the 9.0 release.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
May 1, 2021
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
Added compatibility with Python 3.9.
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.
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 from Exception .
May 1, 2021
Several modules are moved or deprecated.
Aliases provide compatibility for all previously public APIs according to the `backwards-compatibility policy`_
~datastructures.Headers and ~datastructures.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
Added compatibility with Python 3.9.
Added support for IRIs in addition to URIs.
Added close codes 1012, 1013, and 1014.
Raised an error when passing a dict to ~legacy.protocol.WebSocketCommonProtocol.send.
Improved error reporting.
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 ~asyncio.CancelledError inherits from Exception.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
November 1, 2019
Added compatibility with Python 3.8.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
July 31, 2019
Restored the ability to pass a socket with the sock parameter of serve() .
Removed an incorrect assertion when a connection drops.
July 31, 2019
Restored the ability to pass a socket with the sock parameter of ~legacy.server.serve.
Removed an incorrect assertion when a connection drops.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
July 21, 2019
Restored the ability to import WebSocketProtocolError from websockets .
July 21, 2019
Restored the ability to import WebSocketProtocolError from websockets.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
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 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.
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.
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.
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 .
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 ~legacy.server.serve or ~legacy.server.WebSocketServerProtocol, or if you're overriding ~legacy.server.WebSocketServerProtocol.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 ~legacy.protocol.WebSocketCommonProtocol are deprecated.
Use ~legacy.protocol.WebSocketCommonProtocol.local_address in servers and ~legacy.protocol.WebSocketCommonProtocol.remote_address in clients instead of host and port.
WebSocketProtocolError is renamed to ~exceptions.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.
Added ~legacy.auth.basic_auth_protocol_factory to enforce HTTP Basic Auth on the server side.
~legacy.client.connect handles redirects from the server during the handshake.
~legacy.client.connect supports overriding host and port.
Added ~legacy.client.unix_connect for connecting to Unix sockets.
Added support for asynchronous generators in ~legacy.protocol.WebSocketCommonProtocol.send to generate fragmented messages incrementally.
Enabled readline in the interactive client.
Added type hints (484).
Added a FAQ to the documentation.
Added documentation for extensions.
Documented how to optimize memory usage.
~legacy.protocol.WebSocketCommonProtocol.send, ~legacy.protocol.WebSocketCommonProtocol.ping, and ~legacy.protocol.WebSocketCommonProtocol.pong support bytes-like types bytearray and memoryview in addition to bytes.
Added ~exceptions.ConnectionClosedOK and ~exceptions.ConnectionClosedError subclasses of ~exceptions.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.
Prevented spurious log messages about ~exceptions.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.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
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. 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.
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> .
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.
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. See ~legacy.protocol.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 ~asyncio.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 ~legacy.protocol.WebSocketCommonProtocol.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 ~legacy.server.serve and ~legacy.client.connect is renamed to close_timeout .
This prevents confusion with ping_timeout.
For backwards compatibility, timeout is still supported.
The origins argument of ~legacy.server.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 ~asyncio.CancelledError.
Now await ping raises ~exceptions.ConnectionClosed like other public APIs.
Added process_request and select_subprotocol arguments to ~legacy.server.serve and ~legacy.server.WebSocketServerProtocol to facilitate customization of ~legacy.server.WebSocketServerProtocol.process_request and ~legacy.server.WebSocketServerProtocol.select_subprotocol.
Added support for sending fragmented messages.
Added the ~legacy.protocol.WebSocketCommonProtocol.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 ~legacy.protocol.WebSocketCommonProtocol.recv: canceling it at the wrong time could result in messages being dropped.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
July 16, 2018
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.
Added compatibility with Python 3.7.
July 16, 2018
The ~datastructures.Headers class is introduced and several APIs are updated to use it.
The request_headers argument of ~legacy.server.WebSocketServerProtocol.process_request is now a ~datastructures.Headers instead of an http.client.HTTPMessage.
The request_headers and response_headers attributes of ~legacy.protocol.WebSocketCommonProtocol are now ~datastructures.Headers instead of http.client.HTTPMessage.
The raw_request_headers and raw_response_headers attributes of ~legacy.protocol.WebSocketCommonProtocol are removed. Use ~datastructures.Headers.raw_items instead.
Functions defined in the handshake module now receive ~datastructures.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 ~datastructures.Headers instead of lists of (name, value) pairs.
Since ~datastructures.Headers and http.client.HTTPMessage provide similar APIs, much of the code dealing with HTTP headers won't require changes.
Added compatibility with Python 3.7.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
May 24, 2018
Fixed a regression in 5.0 that broke some invocations of serve() and connect() .
May 24, 2018
Fixed a regression in 5.0 that broke some invocations of ~legacy.server.serve and ~legacy.client.connect.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
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 messages ( CVE-2018-1000518 ).
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.
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.
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.
Prevented TypeError due to missing close code on connection close.
Fixed a race condition in the closing handshake that raised InvalidState .
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 messages (CVE-2018-1000518).
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.
~legacy.client.connect performs HTTP Basic Auth when the URI contains credentials.
~legacy.server.unix_serve can be used as an asynchronous context manager on Python ≥ 3.5.1.
Added the ~legacy.protocol.WebSocketCommonProtocol.closed property to protocols.
Added new examples in the documentation.
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 ~legacy.protocol.WebSocketCommonProtocol.ping doesn't receive a pong, it's canceled when the connection is closed.
Reported the cause of ~exceptions.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.
Prevented TypeError due to missing close code on connection close.
Fixed a race condition in the closing handshake that raised ~exceptions.InvalidState.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
November 2, 2017
Fixed issues with the packaging of the 4.0 release.
November 2, 2017
Fixed issues with the packaging of the 4.0 release.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
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.
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 .
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.
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 timeout .
Stopped leaking pending tasks when cancel() is called on a connection while it’s being closed.
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.
If you want to disable compression, add compression=None when calling ~legacy.server.serve or ~legacy.client.connect.
The state_name attribute of protocols is deprecated.
Use protocol.state.name instead of protocol.state_name.
~legacy.protocol.WebSocketCommonProtocol instances can be used as asynchronous iterators on Python ≥ 3.6. They yield incoming messages.
Added ~legacy.server.unix_serve for listening on Unix sockets.
Added the ~legacy.server.WebSocketServer.sockets attribute to the return value of ~legacy.server.serve.
Allowed extra_headers to override Server and User-Agent headers.
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 timeout.
Stopped leaking pending tasks when ~asyncio.Task.cancel is called on a connection while it's being closed.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
August 20, 2017
InvalidStatus is replaced by InvalidStatusCode .
This exception is raised when connect() receives an invalid response status code from the server.
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.
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.
Providing a sock argument to connect() no longer crashes.
August 20, 2017
InvalidStatus is replaced by ~exceptions.InvalidStatusCode.
This exception is raised when ~legacy.client.connect receives an invalid response status code from the server.
~legacy.server.serve can be used as an asynchronous context manager on Python ≥ 3.5.1.
Added support for customizing handling of incoming connections with ~legacy.server.WebSocketServerProtocol.process_request.
Made read and write buffer sizes configurable.
Renamed ~legacy.server.serve and ~legacy.client.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.
Providing a sock argument to ~legacy.client.connect no longer crashes.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
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.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
August 17, 2016
Added timeout , max_size , and max_queue arguments to connect() and serve() .
Made server shutdown more robust.
August 17, 2016
Added timeout, max_size, and max_queue arguments to ~legacy.client.connect and ~legacy.server.serve.
Made server shutdown more robust.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
April 21, 2016
Added flow control for incoming data.
Avoided a warning when closing a connection before the opening handshake.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
December 25, 2015
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 .
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.
Updated documentation with await and async syntax from Python 3.5.
Worked around an asyncio bug affecting connection termination under load.
Improved documentation.
December 25, 2015
~legacy.protocol.WebSocketCommonProtocol.recv now raises an exception when the connection is closed.
~legacy.protocol.WebSocketCommonProtocol.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 ~exceptions.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 ~legacy.server.serve, ~legacy.client.connect, ~legacy.server.WebSocketServerProtocol, or ~legacy.client.WebSocketClientProtocol.
~legacy.client.connect can be used as an asynchronous context manager on Python ≥ 3.5.1.
~legacy.protocol.WebSocketCommonProtocol.ping and ~legacy.protocol.WebSocketCommonProtocol.pong support data passed as str in addition to bytes.
Made state_name attribute on protocols a public API.
Updated documentation with await and async syntax from Python 3.5.
Worked around an asyncio bug affecting connection termination under load.
Improved documentation.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
November 18, 2015
Added compatibility with Python 3.5.
Refreshed documentation.
November 18, 2015
Added compatibility with Python 3.5.
Refreshed documentation.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
August 18, 2015
Added local_address and remote_address attributes on protocols.
Closed open connections with code 1001 when a server shuts down.
Avoided TCP fragmentation of small frames.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
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.
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.
Canceling recv() no longer drops the next message.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
January 31, 2015
Added support for subprotocols.
Added loop argument to connect() and serve() .
January 31, 2015
Added support for subprotocols.
Added loop argument to ~legacy.client.connect and ~legacy.server.serve.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
April 26, 2014
Added host , port and secure attributes on protocols.
Added support for providing and checking Origin .
April 26, 2014
Added host, port and secure attributes on protocols.
Added support for providing and checking Origin.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
February 16, 2014
send() , ping() , and pong() are now coroutines.
They used to be functions.
Instead of:
websocket . send ( message )
you must write:
await websocket . send ( message )
Added flow control for outgoing data.
February 16, 2014
~legacy.protocol.WebSocketCommonProtocol.send, ~legacy.protocol.WebSocketCommonProtocol.ping, and ~legacy.protocol.WebSocketCommonProtocol.pong are now coroutines.
They used to be functions.
Instead of:
websocket.send(message)
you must write:
await websocket.send(message)
Added flow control for outgoing data.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
See https://websockets.readthedocs.io/en/stable/project/changelog.html for details.
November 14, 2013
Initial public release.
On this page
Changelog
Backwards-compatibility policy
17.2
New features
Improvements
Bug fixes
17.1
New features
Improvements
17.0.1
Bug fixes
17.0
Backwards-incompatible changes
New features
Improvements
Bug fixes
16.1.1
Bug fixes
16.1
New features
Improvements
Bug fixes
16.0
Backwards-incompatible changes
New features
Improvements
Bug fixes
15.0.1
Improvements
Bug fixes
15.0
Backwards-incompatible changes
New features
Improvements
14.2
New features
Bug fixes
14.1
Improvements
Bug fixes
14.0
Backwards-incompatible changes
New features
Improvements
Bug fixes
13.1
Backwards-incompatible changes
New features
Improvements
Bug fixes
13.0.1
Bug fixes
13.0
Backwards-incompatible changes
New features
Improvements
Bug fixes
12.0
Backwards-incompatible changes
Improvements
11.0.3
Bug fixes
11.0.2
Bug fixes
11.0.1
Bug fixes
11.0
Backwards-incompatible changes
New features
Improvements
10.4
New features
Improvements
10.3
Backwards-incompatible changes
Improvements
10.2
Improvements
Bug fixes
10.1
New features
Improvements
Bug fixes
10.0
Backwards-incompatible changes
New features
Improvements
Bug fixes
9.1
Security fix
9.0.2
Bug fixes
9.0.1
Bug fixes
9.0
Backwards-incompatible changes
New features
Improvements
Bug fixes
8.1
New features
8.0.2
Bug fixes
8.0.1
Bug fixes
8.0
Backwards-incompatible changes
New features
Improvements
Bug fixes
7.0
Backwards-incompatible changes
New features
Improvements
Bug fixes
6.0
Backwards-incompatible changes
New features
5.0.1
Bug fixes
5.0
Security fix
Backwards-incompatible changes
New features
Improvements
Bug fixes
4.0.1
Bug fixes
4.0
Backwards-incompatible changes
New features
Improvements
Bug fixes
3.4
Backwards-incompatible changes
New features
Improvements
Bug fixes
3.3
New features
Improvements
Bug fixes
3.2
New features
Improvements
3.1
New features
Bug fixes
3.0
Backwards-incompatible changes
New features
Improvements
2.7
New features
Improvements
2.6
New features
Bug fixes
2.5
New features
Improvements
Bug fixes
2.4
New features
2.3
Improvements
2.2
New features
2.1
New features
2.0
Backwards-incompatible changes
New features
1.0
New features
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →