HPACK Header Encoding

4.1.0 verified Tue May 12 auth: no python install: verified quickstart: verified

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.

pip install hpack

Common errors

error ModuleNotFoundError: No module named 'hpack' ↓

cause 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

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

cause 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.

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

cause 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.

error ValueError: Can only encode positive integers, got -1 ↓

cause 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.

Warnings

breaking In 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.

breaking Starting 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.

gotcha Versions 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).

gotcha In 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.

gotcha As 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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 1.29s 18.4M

3.10 slim (glibc) - - 2.10s 19M

3.11 alpine (musl) - - 0.75s 20.0M

3.11 slim (glibc) - - 0.51s 21M

3.12 alpine (musl) - - 0.58s 11.9M

3.12 slim (glibc) - - 0.57s 12M

3.13 alpine (musl) - - 0.60s 11.6M

3.13 slim (glibc) - - 0.63s 12M

3.9 alpine (musl) - - 0.04s 17.6M

3.9 slim (glibc) - - 0.05s 18M

Imports

Encoder
```
from hpack import Encoder
```
Decoder
```
from hpack import Decoder
```

Quickstart verified last tested: 2026-04-23

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}")