Description
# HTTPX WS <p align="center"> <em>WebSockets support for HTTPX</em> </p> [](https://github.com/frankie567/httpx-ws/actions) [](https://codecov.io/gh/frankie567/httpx-ws) [](#contributors) [](https://badge.fury.io/py/httpx-ws) [](https://pepy.tech/project/httpx-ws) --- **Documentation**: <a href="https://frankie567.github.io/httpx-ws/" target="_blank">https://frankie567.github.io/httpx-ws/</a> **Source Code**: <a href="https://github.com/frankie567/httpx-ws" target="_blank">https://github.com/frankie567/httpx-ws</a> --- ## Installation ```bash pip install httpx-ws ``` ## Features - [x] Sync and async client - [x] Helper methods to send text, binary and JSON data - [x] Helper methods to receive text, binary and JSON data - [x] Automatic ping/pong answers - [x] HTTPX transport to test WebSockets defined in ASGI apps - [x] Automatic keepalive ping - [x] `asyncio` and [Trio](https://trio.readthedocs.io/) support through [AnyIO](https://anyio.readthedocs.io/) ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> <!-- prettier-ignore-start --> <!-- markdownlint-disable --> <table> <tbody> <tr> <td align="center" valign="top" width="14.28%"><a href="http://francoisvoron.com"><img src="https://avatars.githubusercontent.com/u/1144727?v=4?s=100" width="100px;" alt="François Voron"/><br /><sub><b>François Voron</b></sub></a><br /><a href="#maintenance-frankie567" title="Maintenance">🚧</a> <a href="https://github.com/frankie567/httpx-ws/commits?author=frankie567" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="http://kousikmitra.github.io"><img src="https://avatars.githubusercontent.com/u/15109533?v=4?s=100" width="100px;" alt="Kousik Mitra"/><br /><sub><b>Kousik Mitra</b></sub></a><br /><a href="https://github.com/frankie567/httpx-ws/commits?author=kousikmitra" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/davidbrochart"><img src="https://avatars.githubusercontent.com/u/4711805?v=4?s=100" width="100px;" alt="David Brochart"/><br /><sub><b>David Brochart</b></sub></a><br /><a href="#platform-davidbrochart" title="Packaging/porting to new platform">📦</a> <a href="https://github.com/frankie567/httpx-ws/commits?author=davidbrochart" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/ysmu"><img src="https://avatars.githubusercontent.com/u/17018576?v=4?s=100" width="100px;" alt="ysmu"/><br /><sub><b>ysmu</b></sub></a><br /><a href="https://github.com/frankie567/httpx-ws/issues?q=author%3Aysmu" title="Bug reports">🐛</a></td> <td align="center" valign="top" width="14.28%"><a href="https://samforeman.me"><img src="https://avatars.githubusercontent.com/u/5234251?v=4?s=100" width="100px;" alt="Sam Foreman"/><br /><sub><b>Sam Foreman</b></sub></a><br /><a href="https://github.com/frankie567/httpx-ws/issues?q=author%3Asaforem2" title="Bug reports">🐛</a></td> <td align="center" valign="top" width="14.28%"><a href="http://maparent.ca/"><img src="https://avatars.githubusercontent.com/u/202691?v=4?s=100" width="100px;" alt="Marc-Antoine Parent"/><br /><sub><b>Marc-Antoine Parent</b></sub></a><br /><a href="https://github.com/frankie567/httpx-ws/issues?q=author%3Amaparent" title="Bug reports">🐛</a> <a href="https://github.com/frankie567/httpx-ws/commits?author=maparent" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://www.fastapiexpert.com/"><img src="https://avatars.githubusercontent.com/u/7353520?v=4?s=100" width="100px;" alt="Marcelo Trylesinski"/><br /><sub><b>Marcelo Trylesinski</b></sub></a><br /><a href="https://github.com/frankie567/httpx-ws/issues?q=author%3AKludex" title="Bug reports">🐛</a> <a href="#research-Kludex" title="Research">🔬</a></td> </tr> <tr> <td align="center" valign="top" width="14.28%"><a href="https://lit.link/MtkN1"><img src="https://avatars.githubusercontent.com/u/51289448?v=4?s=100" width="100px;" alt="MtkN1"/><br /><sub><b>MtkN1</b></sub></a><br /><a href="https://github.com/frankie567/httpx-ws/issues?q=author%3AMtkN1" title="Bug reports">🐛</a> <a href="#research-MtkN1" title="Research">🔬</a> <a href="https://github.com/frankie567/httpx-ws/commits?author=MtkN1" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="http://www.tomchristie.com/"><img src="https://avatars.githubusercontent.com/u/647359?v=4?s=100" width=
Release History
| Version | Changes | Urgency | Date |
|---|---|---|---|
| 0.9.0 | Imported from PyPI (0.9.0) | Low | 4/21/2026 |
| v0.9.0 | Bump version 0.8.2 → 0.9.0 Breaking changes ---------------- Async exceptions are now wrapped in `ExceptionGroup`. Due to the switch to anyio.AsyncContextManagerMixin for cancellation safety, exceptions that propagate out of the async with block are now wrapped in an ExceptionGroup. **Before:** ```py try: async with aconnect_ws("http://localhost:8000/ws") as ws: data = await ws.receive_text() except WebSocketDisconnect: print("Connection closed") ``` **After | Medium | 3/28/2026 |
| v0.8.2 | Bump version 0.8.1 → 0.8.2 Bug fixes and improvements -------------------------- * ASGIWebSocketTransport: increase the initial receive timeout to 1 second and make it configurable via `initial_receive_timeout` parameter. Fix #123 | Low | 11/7/2025 |
| v0.8.1 | Bump version 0.8.0 → 0.8.1 Bug fixes and improvements -------------------------- * Add Python 3.14 support * ASGI transport: fix cancel scope corruption and allow multiple clients on the same transport (#116). Thanks @davidbrochart 🎉 * ASGI transport: avoid hanging indefinitely if the server never accepts the connection. Fix #92. | Low | 10/28/2025 |
| v0.8.0 | Bump version 0.7.2 → 0.8.0 Breaking changes ---------------- * Drop Python 3.9 support Bug fixes and improvements -------------------------- * New class-based API to open clients. [[Documentation](https://frankie567.github.io/httpx-ws/usage/class_based_client/)] Thanks @MtkN1 🎉 * Support WebSocket Denial Response in ASGI transport helper. See #84. * Fix websocket disconnection not properly handled in ASGI transport helper. See #97. | Low | 9/20/2025 |
| v0.7.2 | Bump version 0.7.1 → 0.7.2 Bug fixes --------- * Fix #25: handle broken/disconnected streams more gracefully. Thanks to @runsisi for research and original fix 🎉 | Low | 3/28/2025 |
| v0.7.1 | Bump version 0.7.0 → 0.7.1 Bug fixes and improvements -------------------------- * Fix `ASGIWebSocketAsyncNetworkStream` implementation to avoid async tasks issues. Thanks @graingert 🎉 | Low | 1/4/2025 |
| v0.7.0 | Bump version 0.6.2 → 0.7.0 New features ------------ * Allow to pass a custom `session_class` on `connect_ws`/`aconnect_ws` functions. Thanks @GreyElaina 🎉 Breaking changes ---------------- * Drop Python 3.8 support. Bug fixes and improvements -------------------------- * Fix #29: prevent error when several tasks try to write simultaneously on the same websocket stream. Thanks @GreyElaina 🎉 * Fix #90: don't use a blocking portal to run the ASGIWebSocketTransport. Thanks @ | Low | 12/7/2024 |
| v0.6.2 | Bump version 0.6.1 → 0.6.2 Bug fixes and improvements -------------------------- * Improve efficiency of `WebSocketSession` by reusing a single thread pool when waiting for messages. Thank you @davidbrochart 🎉 | Low | 10/7/2024 |
| v0.6.1 | Bump version 0.6.0 → 0.6.1 Bug fixes --------- * Fix (#73) anyio misusages. Thanks @agronholm 🎉 * Fix (#74) unclosed anyio streams. Thanks @agronholm 🎉 * Fix (#76) memory leak with non-async WebSocketSession. Thanks @ro-oliveira95 🎉 | Low | 10/5/2024 |
| v0.6.0 | Bump version 0.5.2 → 0.6.0 Breaking changes ---------------- * [`AsyncWebSocketSession`](https://frankie567.github.io/httpx-ws/reference/httpx_ws/#httpx_ws.AsyncWebSocketSession) and [`WebSocketSession`](https://frankie567.github.io/httpx-ws/reference/httpx_ws/#httpx_ws.WebSocketSession) no longer accept the `subprotocol` parameter. It's automatically set from the `response` headers (see below). > [!NOTE] > If you only use the `connect_ws` and `aconnect_ws` functions, you don't need t | Low | 4/5/2024 |
| v0.5.2 | Bump version 0.5.1 → 0.5.2 Bug fixes --------- * Set `anyio` dependency lower bound version to `>4` | Low | 3/19/2024 |
| v0.5.1 | Bump version 0.5.0 → 0.5.1 Bug fixes and improvements -------------------------- * Always disable automatic keepalive ping when using ASGI transport. Thanks @dmontagu and @Kludex 🎉 * Bump dependencies: * `httpcore>=1.0.4` - Solves #7, thanks to @tomchristie and @MtkN1 🎉 | Low | 2/22/2024 |
| v0.5.0 | Bump version 0.4.3 → 0.5.0 New features ------------ * `asyncio` and [Trio](https://trio.readthedocs.io/) support through [AnyIO](https://anyio.readthedocs.io/) Breaking changes ---------------- * `WebSocketSession` and `AsyncWebSocketSession` are now context managers. If you were using them directly instead of relying on `connect_ws` and `aconnect_ws`, you'll have to adapt your code accordingly: ```py with WebSocketSession(...) as session: ... async with AsyncWebSocket | Low | 2/9/2024 |
| v0.4.3 | Bump version 0.4.2 → 0.4.3 Bug fixes & improvements ------------------------ * Fix #57: compatibility with `httpx>=0.25.2` * Fix #56: `ASGIWebSocketTransport` returns the correct response from server when opening connection, allowing proper support of subprotocols. | Low | 12/4/2023 |
| v0.4.2 | Bump version 0.4.1 → 0.4.2 Bug fixes --------- * Fix anyio `start_blocking_portal` import. Thanks @maparent 🎉 * Fix #40: handle large message buffering * Fix #34: handle subprotocols corrrectly in `ASGIWebSocketTransport` | Low | 9/27/2023 |
| v0.4.1 | Bump version 0.4.0 → 0.4.1 Bug fixes --------- * Fix import issue with `httpcore>=0.17.3`. Thanks @saforem2 🚀 | Low | 7/6/2023 |
| v0.4.0 | Bump version 0.3.1 → 0.4.0 Breaking changes ---------------- * Drop Python 3.7 support | Low | 6/27/2023 |
| v0.3.1 | Bump version 0.3.0 → 0.3.1 Bug fixes --------- * Fix #30: ASGI transport now correctly handles server errors and closes the WebSocket instead of hanging. Thanks @ysmu 🎉 | Low | 4/15/2023 |
| v0.3.0 | Bump version 0.2.6 → 0.3.0 New features ------------ * Add support for subprotocols [[Doccumentation](https://frankie567.github.io/httpx-ws/usage/subprotocols/)] * Thanks @davidbrochart for the idea and feedback 👍 | Low | 2/15/2023 |
| v0.2.6 | Bump version 0.2.5 → 0.2.6 Bug fixes --------- * Fix case where we try to schedule tasks in new threadpool during client close | Low | 1/3/2023 |
| v0.2.5 | Bump version 0.2.4 → 0.2.5 Bug fixes --------- * Fix #19: when both todo task and wait task are done in `_wait_until_closed`, make sure to always return the todo task result | Low | 1/3/2023 |
| v0.2.4 | Bump version 0.2.3 → 0.2.4 Bug fixes --------- * Fix #15: make sure default HTTPX client is closed. | Low | 12/27/2022 |
| v0.2.3 | Bump version 0.2.2 → 0.2.3 Improvements ------------ * When closing, stop background threads early when they're stuck in a waiting operation | Low | 11/29/2022 |
| v0.2.2 | Bump version 0.2.1 → 0.2.2 Improvements ------------ * Automatic keepalive ping mechanism | Low | 11/28/2022 |
| v0.2.1 | Bump version 0.2.0 → 0.2.1 Improvements ------------ * Handle immediate close from the server in ASGI transport * Improve network errors handling | Low | 11/28/2022 |
| v0.2.0 | Bump version 0.1.1 → 0.2.0 Improvements ------------ * Documentation is live ➡️ https://frankie567.github.io/httpx-ws/ * Revamp implementation with a background thread/task receiving messages * Automatic management of ping/pong events | Low | 11/27/2022 |
| v0.1.1 | Bump version 0.1.0 → 0.1.1 Features -------- * Add a `.ping` method. Thanks @kousikmitra 🎉 Improvements ------------ * Pin lower bound version of `httpx` and `httpcore` dependencies * `httpx>=0.23.1` * `httpcore>=0.16.1` | Low | 11/25/2022 |
| v0.1.0 | Bump version 0.0.0 → 0.1.0 > ⚠️ This is a very young project. Expect bugs 🐛 Features -------- * `connect_ws` helper to talk to WebSockets synchronously. * `aconnect_ws` helper to talk to WebSockets asynchronously. * `ASGIWebSocketTransport` to test WebSockets in ASGI apps directly. | Low | 11/24/2022 |