brotlicffi

library1.2.0.2pypypi✓ verified 25d ago

BrotliCFFI provides Python CFFI bindings to Google's high-performance Brotli compression library. It allows Python applications to leverage the Brotli compression algorithm efficiently across various Python interpreters, including PyPy. The current version is 1.2.0.1, and it maintains an active release cadence with regular updates to the underlying Brotli library and Python compatibility.

serialization http-networking

pip install brotlicffi

github ↗package ↗

INSTALL

IMPORT

SIG · BROTLICFFI

brotlicffi

serializationpythonv1.2.0.2

Install

1.9s avg

Import

10ms

Disk

23MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.0.2 · 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.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.9s · import 0.008s · 25MB

23MB installed

● package 23MB

Code

Verified usage

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

brotlicffi

✓ import brotlicffi

✗ import brotli

Prior to version 0.8.0, the import namespace was 'brotli', which conflicted with Google's native 'brotli' package. The correct import is now 'brotlicffi'.

This quickstart demonstrates basic compression and decompression of a byte string using `brotlicffi.compress()` and `brotlicffi.decompress()`.

import brotlicffi original_data = b"This is some sample data that will be compressed using Brotli!" # Compress data compressed_data = brotlicffi.compress(original_data) print(f"Original size: {len(original_data)} bytes") print(f"Compressed size: {len(compressed_data)} bytes") # Decompress data decompressed_data = brotlicffi.decompress(compressed_data) print(f"Decompressed data: {decompressed_data}") assert original_data == decompressed_data print("Compression and decompression successful!")

Debug

Known issues

breakingPackage renamed from `brotlipy` to `brotlicffi` and import namespace changed from `brotli` to `brotlicffi` to avoid conflicts with Google's official Brotli C bindings.

fix

Update your `pip install` command to `pip install brotlicffi` and change all `import brotli` statements to `import brotlicffi`.

affects: <0.8.0

breakingThe `dictionary` parameter was removed from `brotlicffi.compress()` and `brotlicffi.Compressor`.

fix

Remove the `dictionary` parameter from calls to `compress()` or `Compressor` instantiation.

affects: >=1.0.9.0

breakingSupport for Python 2.7, 3.5, and 3.6 was explicitly removed.

fix

Upgrade your Python environment to Python 3.8 or newer.

affects: >=1.1.0.0

breakingConcurrent sharing of `Compressor` or `Decompressor` objects across multiple threads (especially with Python 3.14's free-threaded build) now raises an exception.

fix

Ensure that `Compressor` and `Decompressor` instances are not shared concurrently between threads. Create a new instance per thread or use appropriate locking mechanisms if sharing is unavoidable.

affects: >=1.2.0.1

gotcha`decompress()` would return an empty bytestring instead of erroring if the provided bytestring was too small or malformed.

fix

This bug was resolved in version 0.6.0. Ensure you are using version 0.6.0 or newer. For older versions, explicitly check the length of the decompressed data.

affects: <0.6.0

gotchaThe `output_buffer_limit` parameter was added to `Decompressor.decompress()` and `Decompressor.process()` methods to mitigate potential security concerns from maliciously crafted compressed data leading to excessive memory usage.

fix

Consider upgrading to version 1.2.0.0 or later and utilizing the `output_buffer_limit` parameter when decompressing untrusted data.

affects: <1.2.0.0

Errors

Common errors & fixes

AttributeError: module 'brotlicffi' has no attribute 'error'

This error typically occurs when code expects an 'error' exception class directly under the `brotlicffi` module, which might have been present in older versions or is a confusion with the `brotli` package's exception handling. The correct exception class in modern `brotlicffi` is `brotlicffi.Error` (capital E).

fix

Replace `brotlicffi.error` with `brotlicffi.Error` in your exception handling. Ensure you are using a compatible version of `brotlicffi` that provides the `Error` exception.

Symbol not found: _BrotliDecoderCreateInstance

This error indicates that the Python CFFI bindings for Brotli (`brotlicffi`) cannot find the underlying C Brotli library function `_BrotliDecoderCreateInstance` during runtime, often due to an incomplete or failed installation, or an incompatibility with the system's C libraries (e.g., `libstdc++` on macOS).

fix

Reinstall `brotlicffi` cleanly using `pip uninstall brotlicffi` followed by `pip install brotlicffi`. If the issue persists, ensure your C compiler toolchain is up-to-date and compatible with your Python version and operating system. On macOS, issues with `libstdc++` might require specific compiler configurations or system updates.

ModuleNotFoundError: No module named 'brotli'

This error occurs when the `brotli` module is imported, but only `brotlicffi` has been installed. Developers often confuse the two packages or follow examples meant for Google's `brotli` CPython bindings.

fix

If you intend to use `brotlicffi`, change your import statement from `import brotli` to `import brotlicffi`. If you need both or prefer the `brotli` package for CPython, install it via `pip install brotli`. A common pattern for cross-implementation compatibility is `try: import brotlicffi as brotli except ImportError: import brotli`.

Exception: Version mismatch: this is the 'cffi' package version X.Y.Z, located in '...', When we import the top-level '_cffi_backend' extension module, we get version A.B.C

This indicates a conflict where different versions of the `cffi` package (which `brotlicffi` depends on) are present in the environment or are being loaded, leading to an inconsistent CFFI backend. This often happens in complex environments or after partial updates.

fix

Ensure a single, consistent version of `cffi` is installed and used. Try `pip uninstall cffi` multiple times until it reports no package found, then reinstall with `pip install cffi`. If using a package manager like `conda`, ensure `cffi` is managed consistently within your environment. Sometimes, explicitly downgrading `cffi` to match an expected version can also resolve this.

Upgrade

Version history

1.2.0.2latest on PyPI · released Aug 21, 2026

Audit

Dependencies

cffirequiredProvides the Foreign Function Interface for Python to call C code.

libbrotli1requiredThe underlying Brotli compression library (shared library, typically installed as a system dependency or bundled).

Agent activity

29 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

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

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