zopfli

library0.4.3pypypi✓ verified 24d ago

Python bindings to the Zopfli Compression Algorithm, offering higher compression ratios than standard zlib or gzip at the cost of significantly slower compression time. It is primarily designed for pre-compressing static assets for web applications or other scenarios where file size is critical and compression is a one-off or build-time operation. Current version 0.4.1 requires Python 3.10+ and maintains an active release cadence, primarily driven by Python version compatibility and updates to the upstream C library.

serialization

pip install zopfli

github ↗package ↗

INSTALL

IMPORT

SIG · ZOPFLI

zopfli

serializationpythonv0.4.3

Install

1.6s avg

Import

—

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.3 · 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

installs and imports cleanly · install 0.0s · import 0.000s · 23.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 21MB

20MB installed

● package 20MB

Code

Verified usage

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

compress

✓ from zopfli.zlib import compress

For Zlib-compatible compression.

compress

✓ from zopfli.gzip import compress

For Gzip-compatible compression.

optimize

✓ from zopfli.png import optimize

For lossless PNG optimization.

Demonstrates basic Zopfli compression using both zlib and gzip formats, including decompression with standard library modules. Also provides a commented example for PNG optimization.

from zopfli.zlib import compress from zopfli.gzip import compress as gzip_compress import zlib from io import BytesIO import gzip data = b"Hello World! This is some data to compress using Zopfli.\n" * 10 # Zlib compression zlib_compressed_data = compress(data, numiterations=15) print(f"Original size: {len(data)} bytes") print(f"Zlib compressed size: {len(zlib_compressed_data)} bytes") assert zlib.decompress(zlib_compressed_data) == data # Gzip compression (note: does not mimic gzip module API directly) gzip_compressed_data = gzip_compress(data, numiterations=15) print(f"Gzip compressed size: {len(gzip_compressed_data)} bytes") with gzip.GzipFile(fileobj=BytesIO(gzip_compressed_data)) as f: assert f.read() == data # PNG optimization (example, requires an actual PNG file) # from zopfli.png import optimize # try: # with open('input.png', 'rb') as f_in: # optimized_png_data = optimize(f_in.read()) # with open('output_optimized.png', 'wb') as f_out: # f_out.write(optimized_png_data) # print("PNG optimized successfully.") # except FileNotFoundError: # print("Skipping PNG optimization: 'input.png' not found.")

Debug

Known issues

breakingPython 3.8 and 3.9 support was dropped in v0.3.0, now requiring Python 3.10 or greater. Similarly, Python 3.7 was dropped in v0.2.3 and 2.7/3.6 in v0.2.0. Users on older Python versions must use an earlier `zopfli` release.

fix

Upgrade Python to 3.10+ or pin `zopfli` to a compatible version (e.g., `<0.3.0` for Python 3.8/3.9).

affects: <0.3.0

breakingStarting from v0.4.0, `zopfli` utilizes CPython's `Py_LIMITED_API` to build `abi3`-tagged wheels. While this reduces the number of wheels and simplifies future Python version compatibility, it might affect users with highly specific CPython ABI requirements or custom build environments.

fix

Most users should be unaffected. If you encounter issues, verify your build chain or environment's compatibility with `abi3` wheels. Rebuilding from source might be necessary in niche cases.

affects: >=0.4.0

gotchaZopfli compression is significantly slower than standard `zlib` or `gzip` (often 100x slower) but yields better compression ratios. It is generally not suitable for on-the-fly compression of dynamic content in web servers.

fix

Use Zopfli for pre-compressing static assets during a build process or deployment, rather than during a user request. Serve pre-compressed files with appropriate `Content-Encoding` headers.

affects: All

gotchaThe `numiterations` parameter (available for `zopfli.zlib.compress` and `zopfli.gzip.compress`) controls the compression effort. Higher values (e.g., 10-15 for small files) result in better compression but drastically increase processing time. For files over several MB, values around 5 are recommended to balance compression and speed.

fix

Experiment with `numiterations` to find the optimal balance for your specific use case. Be mindful of the performance implications.

affects: All

gotchaThe `zopfli.gzip.compress` function does not perfectly mimic the standard library's `gzip` module API for file-like objects or streaming. Decompression of `zopfli.gzip.compress` output typically requires wrapping it with `io.BytesIO` and then `gzip.GzipFile` to read.

fix

When decompressing output from `zopfli.gzip.compress`, use `gzip.GzipFile(fileobj=io.BytesIO(compressed_data)).read()` to ensure correct handling.

affects: All

gotchaAs of v0.4.1, the underlying C `google/zopfli` submodule was switched to the `fonttools/zopfli` fork because the Google repository was archived. This change addresses an unaligned memory access issue that caused `SIGBUS` errors on strict-alignment architectures (e.g., SPARC).

fix

Upgrade to `zopfli` v0.4.1 or newer to benefit from the bug fix and ensure compatibility on strict-alignment architectures.

affects: <0.4.1

Errors

Common errors & fixes

error: Microsoft Visual C++ 14.0 or greater is required.

On Windows, compiling Python packages with C extensions requires the Microsoft Visual C++ build tools, which are not always installed by default.

fix

Install 'Build Tools for Visual Studio' from Microsoft's website, ensuring to select the 'Desktop development with C++' workload. Alternatively, try upgrading `pip` and `setuptools` and then `pip install zopfli` to attempt to use pre-compiled wheels.

fatal error: Python.h: No such file or directory

Compiling the `zopfli` C extension requires the Python development headers and static libraries, which are often not included with the standard Python runtime package on Linux or macOS.

fix

Install the Python development package for your specific Python version (e.g., `sudo apt-get install python3-dev` on Debian/Ubuntu, `sudo dnf install python3-devel` on Fedora/CentOS, or ensure a full Python installation via Homebrew on macOS).

ModuleNotFoundError: No module named 'zopfli'

The `zopfli` library is not installed in the active Python environment or its installation previously failed without a clear error message.

fix

Ensure `zopfli` is correctly installed by running `pip install zopfli`. If installation errors occur, address those first. Verify you are using the Python interpreter where `zopfli` was installed.

TypeError: expected bytes-like object, not str

The `zopfli.compress` or `zopfli.decompress` functions expect byte strings (`bytes`) as input, but a regular Unicode string (`str`) was provided.

fix

Encode the string to bytes before compression (e.g., `my_string.encode('utf-8')`) and decode the resulting bytes back to a string after decompression (e.g., `decompressed_bytes.decode('utf-8')`).

Upgrade

Version history

0.4.3latest on PyPI · released Jun 10, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

33 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/fonttools/py-zopfli ↗

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