hpack

library4.1.0pypypi✓ verified 49d ago

hpack is a pure-Python library implementing the HPACK (Header Compression for HTTP/2) algorithm, adhering strictly to RFC 7541. It provides `Encoder` and `Decoder` classes for compressing and decompressing HTTP/2 headers efficiently. Maintained by the python-hyper project, it is currently at version 4.1.0 and sees releases periodically, with major versions several years apart, indicating stable and active maintenance.

http-networking

pip install hpack

github ↗package ↗docs ↗

Install & Compatibility

Where this runs

tested against v4.1.0 · 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

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.540s · 18.4MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 1.6s · import 0.642s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Encoder

✓ from hpack import Encoder

Decoder

✓ from hpack import Decoder

Initializes an HPACK Encoder and Decoder, then demonstrates encoding a list of HTTP/2 headers into bytes and subsequently decoding them back to a list of header tuples.

from hpack import Encoder, Decoder # Example headers headers = [ (':method', 'GET'), (':path', '/resource'), ('user-agent', 'hpack-client/1.0'), ('accept-encoding', 'gzip, deflate, br') ] # Encode headers encoder = Encoder() encoded_bytes = encoder.encode(headers) print(f"Encoded bytes: {encoded_bytes.hex()}") # Decode headers decoder = Decoder() decoded_headers = decoder.decode(encoded_bytes) print(f"Decoded headers: {decoded_headers}")

Debug

Known issues

breakingIn version 3.0.0, the explicit support for the `nghttp2` C-based backend was temporarily removed due to being non-functional. While later versions have re-integrated transparent `nghttp2` usage, this change was breaking for applications directly relying on `nghttp2` integration in 3.0.0.

fix

Review `nghttp2` integration. For 3.0.0, consider using pure-Python implementation or downgrading/upgrading past 3.0.0 if `nghttp2` performance is critical. Newer versions (4.x) handle `nghttp2` transparently if installed.

affects: 3.0.0

breakingStarting with version 3.0.0, the `Encoder` strictly enforces the maximum allowed header table size. Attempts to exceed this limit via dynamic table size updates will now raise `InvalidTableSizeError`.

fix

Ensure your encoding logic respects the `Encoder`'s header table size limits. Catch `InvalidTableSizeError` if necessary and adjust header field handling.

affects: >=3.0.0

gotchaVersions of `hpack` prior to 2.3.0 were vulnerable to the 'HPACK Bomb' denial-of-service attack (CVE-2016-6581), where a small compressed header block could decompress into a disproportionately large amount of memory. Version 2.3.0 introduced `Decoder.max_header_list_size` to mitigate this.

fix

Upgrade to `hpack` version 2.3.0 or newer immediately. Configure `Decoder.max_header_list_size` to a sensible limit to protect against this vulnerability (default is 64kB).

affects: <2.3.0

gotchaIn versions 2.1.0 and 2.3.0, several generic exceptions (`IndexError`, `UnicodeDecodeError`) raised during decoding were replaced with more specific `HPACKDecodingError` and `InvalidTableIndex`. Code catching the older, broader exceptions might no longer correctly handle specific HPACK-related failures.

fix

Update exception handling to catch `HPACKDecodingError` or its subclasses like `InvalidTableIndex` for more precise error management during HPACK decoding.

affects: >=2.1.0

gotchaAs of version 2.2.0, the `Decoder.decode()` method returns `HeaderTuple` or `NeverIndexedHeaderTuple` objects instead of plain tuples. While these behave largely like 2-tuples, code performing strict type-checking (e.g., `isinstance(header, tuple)`) might be affected.

fix

Adjust type checks to acknowledge `HeaderTuple` or rely on duck-typing if only tuple-like behavior (iteration, indexing) is expected. These objects are subclasses of `tuple` and should be compatible for most uses.

affects: >=2.2.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'hpack'

The 'hpack' library is not installed in your Python environment or the Python interpreter cannot find it in its search path.

fix

Install the hpack library using pip: `pip install hpack`

hpack.exceptions.HPACKDecodingError: Unable to decode headers as UTF-8.

The HPACK-encoded header block contains byte sequences that cannot be correctly decoded as UTF-8, which is the default decoding for header values in hpack.

fix

Ensure that the input data to the `Decoder.decode()` method is valid HPACK, and if header values are not strictly UTF-8, consider using `d.decode(encoded_bytes, raw=True)` to receive raw byte strings for header values.

hpack.exceptions.OversizedHeaderListError: A header list larger than <max_size> has been received

The decompressed size of the header list exceeds the maximum allowed size configured for the `hpack.Decoder` instance (defaulting to 64kB to prevent 'HPACK Bomb' attacks).

fix

If safe and necessary, increase the `max_header_list_size` limit when initializing the `hpack.Decoder`: `d = Decoder(max_header_list_size=131072)` (for 128kB). Otherwise, the received header block is considered malicious or malformed and the connection should be shut down.

ValueError: Can only encode positive integers, got -1

An attempt was made to encode a negative integer using an hpack function (e.g., `encode_integer`) that only accepts non-negative or positive integer values as per the HPACK specification.

fix

Ensure that all integer inputs to hpack encoding functions adhere to the specified constraints, typically requiring positive or non-negative values.

Upgrade

Version history

4.1.0latest on PyPI

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

seranking-bot

ahrefsbot

node

Amazon

bytedance

googlebot

Resources

githubhttps://github.com/python-hyper/hpack ↗

packagehttps://pypi.org/project/hpack/ ↗

docshttps://python-hyper.org/ ↗