Zopfli for Python

0.4.1 · active · verified Sun Apr 05

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.

Warnings

breaking Python 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).
breaking Starting 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.
gotcha Zopfli 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.
gotcha The `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.
gotcha The `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.
gotcha As 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.

Install

pip install zopfli Install latest stable version

Imports

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.

Quickstart

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

view raw JSON →