isal

library1.8.0pypypi✓ verified 22d ago

isal (python-isal) provides faster zlib and gzip compatible compression and decompression by offering Python bindings for the Intel® Intelligent Storage Acceleration Library (ISA-L). It includes `isal_zlib` and `igzip` as high-performance, largely drop-in replacements for the standard library's `zlib` and `gzip` modules, respectively, along with `igzip_threaded` for multi-threaded streaming and `igzip_lib` for direct ISA-L API access. The current version is 1.8.0, and it maintains an active development and release cadence.

serialization data

pip install isal

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · ISAL

isal

serializationpythonv1.8.0

Install

1.6s avg

Import

10ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

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

installs and imports cleanly · install 0.0s · import 0.004s · 18.7MB

glibc

py 3.10–3.95 runs

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

17MB installed

● package 17MB

Code

Verified usage

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

isal_zlib

✓ from isal import isal_zlib

Drop-in replacement for the standard `zlib` module.

igzip

✓ from isal import igzip

Drop-in replacement for the standard `gzip` module.

igzip_threaded

✓ from isal import igzip_threaded

Provides multi-threaded buffered read/write streams.

igzip_lib

✓ from isal import igzip_lib

Direct access to ISA-L's compression functions.

This example demonstrates basic compression and decompression using `isal_zlib`, highlighting its direct compatibility with the standard `zlib` module's API.

from isal import isal_zlib original_data = b"Python-isal offers faster compression and decompression." * 10 # Compress data compressed_data = isal_zlib.compress(original_data) # Decompress data decompressed_data = isal_zlib.decompress(compressed_data) assert original_data == decompressed_data print(f"Original size: {len(original_data)} bytes") print(f"Compressed size: {len(compressed_data)} bytes") print("Data compressed and decompressed successfully using isal_zlib.")

Debug

Known issues

breakingAs of a recent release (likely 1.8.0), Python 3.8 and 3.9 are no longer officially supported, despite PyPI metadata potentially indicating support for `>=3.9`.

fix

Ensure your project runs on Python 3.10 or newer.

affects: 1.8.0 and later

gotchaCompression level `0` in `isal_zlib` and `igzip` corresponds to the *lowest* compression level, unlike `zlib` and `gzip` where `0` means 'no compression'.

fix

Adjust compression level usage or explicitly choose a higher level if you expect actual compression.

affects: All versions

gotcha`isal_zlib` primarily supports `Z_DEFAULT_STRATEGY`. While other strategies are exposed for compatibility, using them may result in warnings as ISA-L might not fully implement them.

fix

Prefer `Z_DEFAULT_STRATEGY` or be aware that other strategies might behave differently or issue warnings.

affects: All versions

gotcha`igzip_threaded`'s `open` function returns buffered read/write streams that are designed for streaming only and do not support seeking operations.

fix

Use `igzip` for files requiring seeking, or manage your data in a strictly streaming fashion with `igzip_threaded`.

affects: All versions

gotcha`igzip.open` returns an `IGzipFile` class instance, not the standard `GzipFile`. While `igzip.GzipFile` exists as an alias for compatibility, direct type checking or relying on `GzipFile`-specific internal behavior might break.

fix

When using `igzip.open`, avoid strict type checks against `gzip.GzipFile` or use `igzip.GzipFile` alias if specific compatibility is needed.

affects: All versions

Errors

Common errors & fixes

error: subprocess-exited-with-error

The `isal` library has C extensions and requires build tools (like a C compiler, `autoconf`, `automake`, `libtool`) to be present on the system for successful installation, especially if a pre-built wheel is not available for the specific platform or Python version.

fix

Install the necessary build dependencies for your operating system (e.g., `sudo apt-get install build-essential zlib1g-dev autoconf automake libtool` on Debian/Ubuntu, or corresponding development tools on other platforms) before running `pip install isal`.

ModuleNotFoundError: No module named 'isal_zlib'

This error occurs if the `isal` package is not installed, or if the `isal_zlib` submodule is being imported incorrectly, for example, by trying to import it directly instead of from the `isal` package.

fix

First, ensure `isal` is installed via `pip install isal`. Then, correct the import statement to `from isal import isal_zlib` or `from isal import igzip` as per the library's structure.

Other flush modes are not supported and will raise errors.

`isal_zlib` and `igzip` have a more limited set of supported flush modes (NO_FLUSH, SYNC_FLUSH, FULL_FLUSH, FINISH_FLUSH) compared to the standard Python `zlib` module, and using unsupported modes will result in an error.

fix

When using `isal_zlib` or `igzip`, ensure you only use the explicitly supported flush modes: `isal_zlib.NO_FLUSH`, `isal_zlib.SYNC_FLUSH`, `isal_zlib.FULL_FLUSH`, or `isal_zlib.FINISH_FLUSH`.

OSError: igzip: Error while decompressing extra concatenated gzip files

This error can occur when `igzip` attempts to decompress a gzip file that contains multiple concatenated gzip streams, especially with certain file structures or when using an older version of the underlying ISA-L library.

fix

Try updating the `isal` package to its latest version, as updates may address issues with ISA-L builds and file handling. Alternatively, pre-process the problematic gzip file to ensure it contains only a single valid gzip stream, for example, by decompressing and re-compressing it using standard `gzip` or `pigz`.

Upgrade

Version history

1.8.0latest on PyPI · released Sep 10, 2025

Audit

Dependencies

ISA-LrequiredProvides the underlying accelerated compression algorithms. Wheels typically include a statically linked version; source builds may require ISA-L development headers.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/pycompression/python-isal ↗

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

docshttps://python-isal.readthedocs.io ↗