Install & Compatibility
Where this runs
tested against v0.13.1 · 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
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.0s · import 0.371s · 119MB
121MB installed
● package 121MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
numcodecs
✓ import numcodecs
Blosc
✓ from numcodecs.blosc import Blosc
✗ from numcodecs import Blosc
Specific codecs like Blosc, Zstd, GZip reside in their own submodules, not directly under the top-level numcodecs namespace.
Zstd
✓ from numcodecs.zstd import Zstd
✗ from numcodecs import Zstd
Specific codecs like Blosc, Zstd, GZip reside in their own submodules, not directly under the top-level numcodecs namespace.
GZip
✓ from numcodecs.gzip import GZip
✗ from numcodecs import GZip
Specific codecs like Blosc, Zstd, GZip reside in their own submodules, not directly under the top-level numcodecs namespace.
This quickstart demonstrates how to instantiate a codec (Blosc or GZip as a fallback), encode a NumPy array into bytes, and then decode it back. It also shows how to globally register and retrieve codecs, which is often used in frameworks like Zarr.
import numpy as np
import numcodecs
# Define some data to encode
data = np.arange(10000, dtype='i4').reshape(100, 100)
# Choose a codec. Blosc is common, but requires 'pip install "numcodecs[blosc]"'.
# If Blosc isn't installed, GZip is a good fallback.
try:
codec = numcodecs.blosc.Blosc(cname='lz4', clevel=5, shuffle=numcodecs.blosc.SHUFFLE)
print("Using Blosc codec.")
except ImportError:
print("Blosc not installed. Falling back to GZip codec.")
codec = numcodecs.gzip.GZip(level=5)
# Encode the data
encoded_data = codec.encode(data.tobytes())
print(f"Original data shape: {data.shape}, dtype: {data.dtype}")
print(f"Original bytes: {data.nbytes}")
print(f"Encoded bytes: {len(encoded_data)}")
# Decode the data
decoded_bytes = codec.decode(encoded_data)
# Reconstruct the numpy array
decoded_data = np.frombuffer(decoded_bytes, dtype=data.dtype).reshape(data.shape)
# Verify that the decoded data matches the original
assert np.array_equal(data, decoded_data)
print("Data successfully encoded and decoded!")
# You can also register codecs globally for retrieval by ID
numcodecs.register_codec(codec)
retrieved_codec = numcodecs.get_codec({'id': codec.codec_id, **codec.get_config()})
assert retrieved_codec.codec_id == codec.codec_id
print(f"Codec '{retrieved_codec.codec_id}' registered and retrieved successfully.")
Errors
Common errors & fixes
ERROR: Failed building wheel for numcodecs
This error typically occurs during `pip install numcodecs` when the C extensions (e.g., for Blosc) fail to compile due to missing build tools (like a C compiler on Windows or specific `glibc` versions on Linux) or environment issues.
fixEnsure you have the necessary build tools installed for your operating system (e.g., 'Build Tools for Visual Studio' on Windows, or `gcc` on Linux). Alternatively, install `numcodecs` via `conda`, which provides pre-compiled binaries: `conda install -c conda-forge numcodecs`.
ImportError: cannot import name 'blosc'
This error indicates that the Blosc C extension for `numcodecs` failed to compile or load correctly during installation, often when using `pip` without the necessary build environment, resulting in the `blosc` module not being available.
fixInstall `numcodecs` using `conda` (`conda install -c conda-forge numcodecs`) to get pre-compiled binaries, or ensure your `pip` installation environment has a working C compiler (e.g., by installing `build-essential` on Debian/Ubuntu or Xcode Command Line Tools on macOS) and try `pip install numcodecs -v --no-cache-dir --no-binary numcodecs numcodecs` to force a rebuild with verbose output.
ImportError: cannot import name 'cbuffer_sizes' from 'numcodecs.blosc'
This error occurs when an older version of Zarr (specifically `zarr<3`) attempts to import functions like `cbuffer_sizes` or `cbuffer_metainfo` from `numcodecs.blosc`, but these functions have been deprecated and removed in `numcodecs` versions 0.16.0 and later.
fixUpgrade your Zarr library to version 3 or newer (`pip install --upgrade zarr`) which is compatible with recent `numcodecs` versions, or downgrade `numcodecs` to a version prior to 0.16.0 (e.g., `pip install numcodecs<0.16.0`) to maintain compatibility with `zarr<3`.
RuntimeError: error during blosc decompression: -1
This runtime error often points to an issue during the decompression of Blosc-compressed data. It can be caused by incompatibility between the `glibc` version where `numcodecs` (specifically its Blosc extension) was built and the `glibc` version on the system where the code is being run (common in HPC environments) or data corruption.
fixTry installing `numcodecs` using `conda` from `conda-forge` (`conda install -c conda-forge numcodecs`) on the target machine, as `conda-forge` packages are often built with broader `glibc` compatibility. If the issue persists, verify data integrity or check for environment inconsistencies between where the data was created and where it's being accessed.
numcodecs.errors.UnknownCodecError: codec not available: 'zfpy'
This error means you are trying to use an optional codec (like ZFPY, PCodec, or CRC32C) whose underlying Python dependency is not installed. `numcodecs` will not define the codec class if its required external library is missing.
fixInstall the missing dependency for the specific codec you wish to use. For 'zfpy', install `zfpy` (`pip install zfpy` or `conda install -c conda-forge zfpy`). Similarly, for 'pcodec' you would install `pcodec` (`pip install pcodec`).
Upgrade
Version history
0.16.5latest on PyPI · released Nov 21, 2025
Audit
Dependencies
numpyrequiredMost codecs operate on NumPy arrays; while not a strict install_requires, it's a de-facto dependency for practical use.
zarroptionalOften used in conjunction with Zarr for array compression and serialization.
bloscoptionalProvides the highly optimized Blosc compression codec.
python-lz4optionalProvides the fast LZ4 compression codec.
python-snappyoptionalProvides the Snappy compression codec.
python-zstdoptionalProvides the Zstd compression codec.