Install & Compatibility
Where this runs
tested against v0.3.24 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Encoder
✓ from pylsqpack import Encoder
Decoder
✓ from pylsqpack import Decoder
This quickstart demonstrates how to initialize an `Encoder` and `Decoder`, encode a list of HTTP/3 headers, and then decode the resulting header block. Note the use of bytes for header names and values, and the `max_table_capacity` and `blocked_streams` parameters for the `Decoder` (and implicitly for `Encoder` settings which would be exchanged via HTTP/3 SETTINGS frames). [2, 7]
from pylsqpack import Encoder, Decoder
# Example HTTP/3 headers
headers = [
(b':method', b'GET'),
(b':scheme', b'https'),
(b':path', b'/resource'),
(b':authority', b'example.org'),
(b'user-agent', b'pylsqpack-example/1.0')
]
# Encoder initialization
# The exact values for max_table_capacity and blocked_streams depend on QPACK settings
e = Encoder()
# Encode headers for stream ID 0
# The encode method returns a tuple: (encoder_stream_data, encoded_header_block)
encoder_stream_data, encoded_header_block = e.encode(0, headers)
print("Original Headers:", headers)
print("Encoded Header Block:", encoded_header_block)
# Decoder initialization
# max_table_capacity and blocked_streams must match peer's settings
d = Decoder(max_table_capacity=4096, blocked_streams=100)
# Feed encoder stream data to the decoder, if any
# (In simple encode/decode, this might be empty, but important for full QPACK interaction)
if encoder_stream_data:
unblocked_streams = d.feed_encoder_stream(encoder_stream_data)
# For actual HTTP/3, you'd then resume decoding for unblocked_streams
# Decode the header block for stream ID 0
try:
control_data, decoded_headers = d.decode(0, encoded_header_block)
print("Decoded Headers:", decoded_headers)
except Exception as e:
print(f"Decoding failed: {e}")
Debug
Known issues
breakingThe underlying `ls-qpack` C library, which `pylsqpack` wraps, underwent significant API changes in its 2.x versions. `pylsqpack` did not immediately update to `ls-qpack` 2.x due to these substantial changes. Users expecting direct compatibility or features available only in `ls-qpack` 2.x may encounter mismatches. [10]fixConsult the `pylsqpack` documentation or GitHub issues for updates regarding `ls-qpack` 2.x compatibility. Ensure the features you need are supported by the `ls-qpack` version `pylsqpack` is built against.
affects: <=0.3.24 (compared to `ls-qpack` 2.x)
gotcha`pylsqpack` is a wrapper around a C library (`ls-qpack`). Its behavior and performance are inherently tied to the underlying C implementation. Advanced usage, performance tuning, or debugging complex QPACK scenarios may require a conceptual understanding of the QPACK specification and the `ls-qpack` C API beyond just the Python bindings. [1, 2, 3]fixFamiliarize yourself with the QPACK specification and the `ls-qpack` library's design principles, especially for production environments or when deep customization is required.
affects: All versions
gotchaThe `Decoder` and `Encoder` constructors require `max_table_capacity` and `blocked_streams` parameters. These are crucial QPACK-specific settings. Incorrectly setting these values (e.g., not matching the values advertised by the peer via HTTP/3 SETTINGS frames) can lead to suboptimal compression/decompression, stream blocking, or outright decoding failures. [2]fixEnsure that `max_table_capacity` and `blocked_streams` are set correctly based on the QPACK settings exchanged with the peer in your HTTP/3 connection. Refer to the QPACK specification (RFC 9204) for details on these parameters.
affects: All versions
Errors
Common errors & fixes
src/pylsqpack/binding.c: In function 'Decoder_init': src/pylsqpack/binding.c:93:77: warning: passing argument 5 of 'lsqpack_dec_init' from incompatible pointer type
This error, often accompanied by other `gcc` warnings/errors like 'use of undefined type' or 'too many arguments to function', indicates a compilation failure during `pylsqpack` installation. It typically arises from an incompatibility between the `pylsqpack` wrapper code and the version of the underlying `ls-qpack` C library headers found on the system, where the C API signatures have changed. [5]
fixEnsure you have a compatible version of the `ls-qpack` library installed, or try updating `pylsqpack` to its latest version, which might include fixes for newer `ls-qpack` APIs. If building from source, ensure development headers for `ls-qpack` are correctly linked. Sometimes, installing via `pip install pylsqpack` in a clean environment resolves pre-compilation issues by using pre-built wheels or fetching compatible dependencies. [1]
Problem: cannot install the best candidate for the job - nothing provides (python3.9dist(pylsqpack) < 0.4 with python3.9dist(pylsqpack) >= 0.3.3) needed by python3-aioquic
This error occurs in package managers like `dnf` when trying to install a Python application (e.g., `aioquic`) that has `pylsqpack` as a dependency, but the specified version constraints for `pylsqpack` cannot be met by available packages in the repository. This often indicates a version mismatch or missing package. [4]
fixTry to install `pylsqpack` directly first using `pip install pylsqpack`. If the issue persists, check the available versions of `pylsqpack` and its dependent packages in your system's repositories or PyPI to ensure compatibility. You might need to install a specific version of `pylsqpack` that satisfies the dependency requirements of `aioquic`, for example, by adjusting your environment or using a virtual environment to manage dependencies. [1, 4]
ModuleNotFoundError: No module named 'pylsqpack'
This is a standard Python error indicating that the `pylsqpack` package was not found in the Python environment's installed libraries. This usually happens if the package was not installed, installed in a different environment, or if the Python interpreter being used cannot access the installed package. [10]
fixInstall the package using pip: `pip install pylsqpack`. If you are using virtual environments, ensure you activate the correct environment before installation and execution. Verify installation with `pip show pylsqpack`. [1]
pylsqpack.EncoderStreamError: Encoder stream error
This error is raised by `pylsqpack.Encoder` when the data provided to its stream cannot be processed, typically due to malformed input or an unexpected state in the QPACK encoding process. [3]
fixReview the data being fed to the `Encoder` object. Ensure that headers are properly formatted as a list of `(name, value)` byte-tuples. Check the state of the encoder and the parameters passed to `encode()` or `feed_encoder_stream()`. Consult the `pylsqpack` documentation for expected input formats and method usage. [3]
struct.error: integer out of range for 'q' format code
While not directly from `pylsqpack` snippets, this error commonly arises in Python when interacting with C libraries (which `pylsqpack` does) via the `struct` module or similar mechanisms. It indicates an attempt to pack an integer value that exceeds the representable range for a specified C type (e.g., 'q' for a signed long long) when `pylsqpack` is internally converting Python integers to C integer types for QPACK operations. [12]
fixExamine the integer values being passed to `pylsqpack` methods, particularly those related to capacities, stream IDs, or header lengths. Ensure these values fall within the expected range for the underlying C data types. If dealing with unsigned values, verify that `pylsqpack` methods correctly handle them or convert them appropriately before passing. [12]
Upgrade
Version history
0.3.24latest on PyPI · released Mar 29, 2026
Audit
Dependencies
ls-qpackrequiredpylsqpack is a wrapper around the `ls-qpack` C library. The C library is typically bundled within the prebuilt wheels.