{"id":2374,"library":"aioquic","title":"aioquic","description":"aioquic is a pure-Python library for the QUIC network protocol and HTTP/3, featuring a minimal TLS 1.3 implementation. It follows a 'bring your own I/O' (sans-I/O) design, making it suitable for embedding in various frameworks. As of version 1.3.0, it supports QUIC v1 (RFC 9000), QUIC v2 (RFC 9369), and HTTP/3 (RFC 9114). The library is actively maintained with frequent updates and is regularly tested for interoperability against other QUIC implementations.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/aiortc/aioquic","tags":["async","quic","http/3","networking","tls"],"install":[{"cmd":"pip install aioquic","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for TLS 1.3 implementation and cryptographic operations within QUIC.","package":"cryptography"},{"reason":"Required for building aioquic from source, as it includes C extensions for performance-critical cryptographic operations.","package":"OpenSSL development headers","optional":true}],"imports":[{"note":"Commonly used in asyncio-based client and server implementations.","symbol":"QuicConnectionProtocol","correct":"from aioquic.asyncio import QuicConnectionProtocol"},{"note":"Used by asyncio clients to initiate a QUIC connection.","symbol":"connect","correct":"from aioquic.asyncio import connect"},{"note":"Used by asyncio servers to listen for incoming QUIC connections.","symbol":"serve","correct":"from aioquic.asyncio import serve"},{"note":"Essential for configuring QUIC parameters like ALPN protocols, TLS certificates, and keys.","symbol":"QuicConfiguration","correct":"from aioquic.quic.configuration import QuicConfiguration"},{"note":"Specifies the Application-Layer Protocol Negotiation (ALPN) token for HTTP/3.","symbol":"H3_ALPN","correct":"from aioquic.h3.connection import H3_ALPN"},{"note":"Represents the HTTP/3 layer for sending and receiving HTTP/3 events.","symbol":"H3Connection","correct":"from aioquic.h3.connection import H3Connection"},{"note":"Event type representing received HTTP/3 headers.","symbol":"HeadersReceived","correct":"from aioquic.h3.events import HeadersReceived"},{"note":"Event type representing received HTTP/3 data.","symbol":"DataReceived","correct":"from aioquic.h3.events import DataReceived"}],"quickstart":{"code":"import asyncio\nimport logging\nfrom typing import Optional\n\nfrom aioquic.asyncio import connect\nfrom aioquic.asyncio.protocol import QuicConnectionProtocol\nfrom aioquic.h3.connection import H3_ALPN, H3Connection\nfrom aioquic.h3.events import DataReceived, HeadersReceived, H3Event\nfrom aioquic.quic.configuration import QuicConfiguration\nfrom aioquic.quic.events import QuicEvent\n\nclass HttpClientProtocol(QuicConnectionProtocol):\n    def __init__(self, *args, **kwargs):\n        super().__init__(*args, **kwargs)\n        self._http = H3Connection(self._quic)\n        self._buffer = b''\n        self._http_events = asyncio.Queue()\n        self._task = asyncio.create_task(self._http_event_handler())\n\n    async def _http_event_handler(self):\n        while True:\n            event = await self._http_events.get()\n            if isinstance(event, HeadersReceived):\n                for k, v in event.headers:\n                    print(f\"Header: {k.decode()} = {v.decode()}\")\n            elif isinstance(event, DataReceived):\n                self._buffer += event.data\n                if event.stream_ended:\n                    print(f\"Body: {self._buffer.decode()}\")\n                    self._buffer = b''\n\n    def quic_event_received(self, event: QuicEvent) -> None:\n        self._http.handle_event(event)\n        while True:\n            http_event = self._http.pull_http_event()\n            if http_event is None:\n                break\n            self._http_events.put_nowait(http_event)\n\n    async def get(self, url: str):\n        headers = [\n            (b\":method\", b\"GET\"),\n            (b\":scheme\", b\"https\"),\n            (b\":authority\", url.encode()),\n            (b\":path\", b\"/\"),\n            (b\"user-agent\", b\"aioquic-client/1.0\"),\n        ]\n        stream_id = self._http.send_headers(stream_id=self._http.get_next_available_stream_id(), headers=headers)\n        self._http.send_data(stream_id=stream_id, data=b'', end_stream=True)\n        self.transmit()\n\nasync def main():\n    logging.basicConfig(level=logging.INFO)\n\n    configuration = QuicConfiguration(\n        is_client=True,\n        alpn_protocols=H3_ALPN,\n    )\n    # For testing against a local server with a self-signed cert, you might need to disable certificate verification\n    # configuration.verify_mode = ssl.CERT_NONE\n\n    host = \"quic.aiortc.org\"\n    port = 4433\n\n    async with connect(\n        host=host,\n        port=port,\n        configuration=configuration,\n        create_protocol=HttpClientProtocol,\n    ) as client_protocol:\n        await client_protocol.get(host)\n        await asyncio.sleep(1) # Give time for events to be processed\n\nif __name__ == \"__main__\":\n    asyncio.run(main())","lang":"python","description":"This quickstart demonstrates a basic HTTP/3 client using `aioquic` to connect to a server and fetch content. It initializes a `QuicConfiguration` for client-side operation with HTTP/3 ALPN, then connects to a specified host and port. The `HttpClientProtocol` handles QUIC events, processes HTTP/3 headers and data, and prints the response body. This example showcases how to establish a connection and make a simple GET request."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or higher.","message":"As of version 1.3.0, aioquic has dropped support for Python 3.8 and 3.9. Users must use Python 3.10 or newer. Newer versions also include support for Python 3.13 and 3.14.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"Install OpenSSL development headers for your operating system (e.g., `sudo apt install libssl-dev python3-dev` on Debian/Ubuntu, `brew install openssl` on macOS).","message":"When building aioquic from source (e.g., if pre-built wheels are not available for your platform), you must have OpenSSL development headers installed on your system. This is a common non-Python dependency that can cause installation failures.","severity":"gotcha","affected_versions":"All versions (when building from source)"},{"fix":"For simplified I/O, utilize the `aioquic.asyncio` module and its `QuicConnectionProtocol`, `connect`, and `serve` functions. When using the lower-level `QuicConnection` directly, ensure you regularly call `datagrams_to_send()` and handle `receive_datagram()` based on network events.","message":"The core QUIC and HTTP/3 APIs in aioquic follow a 'sans-I/O' pattern, meaning they do not perform network I/O directly. Users are responsible for sending and receiving UDP datagrams. While the `aioquic.asyncio` API provides convenience, direct interaction with `QuicConnection` requires manual datagram handling, which can be a point of confusion for new users.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Generate a self-signed certificate and key (e.g., using OpenSSL: `openssl req -x509 -newkey rsa:4096 -nodes -out cert.pem -keyout key.pem -days 365`) and configure `QuicConfiguration` with `certificatefile` and `private_key_file`.","message":"Running an aioquic server, especially for HTTP/3, requires a TLS certificate and private key. For development or testing, self-signed certificates can be generated, but their presence and correct configuration in `QuicConfiguration` are mandatory.","severity":"gotcha","affected_versions":"All versions (for server implementations)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}