Install & Compatibility
Where this runs
tested against v2.18.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
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.7s · import 0.934s · 123MB
127MB installed
● package 127MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
zarr.create_array
✓ import zarr
z = zarr.create_array(...)
✗ from zarr import Array
z = Array(...)
Direct construction of `zarr.Array` is discouraged in Zarr-Python 3. Use `zarr.create_array` or `zarr.open_array` instead.
zarr.codecs.BloscCodec
✓ import zarr.codecs
compressors=zarr.codecs.BloscCodec(...)
✗ from zarr import Blosc
compressors=Blosc(...)
As of Zarr-Python 3.0, codecs like Blosc must be imported from `zarr.codecs` or directly from `numcodecs`, not from the top-level `zarr` module.
This quickstart demonstrates how to create a Zarr array, assign data to it using NumPy, and retrieve a subset. The array is stored on the local filesystem. This example defaults to Zarr format 3, which is the standard for Zarr-Python 3.x and newer.
import zarr
import numpy as np
import os
# Create a directory for the Zarr store
store_path = 'data/example_zarr_array.zarr'
os.makedirs(os.path.dirname(store_path), exist_ok=True)
# Create a 2D Zarr array
# This will default to Zarr format 3
z_array = zarr.create_array(
store=store_path,
shape=(100, 100),
chunks=(10, 10),
dtype='f4'
)
# Assign data to the array
z_array[:, :] = np.random.random((100, 100))
print(f"Created Zarr array at: {store_path}")
print(f"Array info:\n{z_array.info}")
# Access data
subset = z_array[0:5, 0:5]
print(f"Subset of array:\n{subset}")
# Clean up the created directory
import shutil
shutil.rmtree('data')
Debug
Known issues
breakingZarr-Python 3.0 introduced significant breaking changes compared to 2.x, particularly a major refactor of the API, storage layer, and codec handling. Direct imports of codecs (e.g., `Blosc`) from `zarr.*` are no longer supported; they must be imported directly from `zarr.codecs` or `numcodecs`. Direct construction of `zarr.Array` is discouraged in favor of `zarr.create_array` or `zarr.open_array`.fixReview the Zarr-Python 3.0 Migration Guide. Update codec imports (e.g., `from zarr.codecs import BloscCodec` or `from numcodecs import BloscCodec`). Use `zarr.create_array` or `zarr.open_array` for array creation.
affects: >=3.0.0
breakingNewly created arrays in Zarr-Python 3.0 and later default to Zarr format 3. This means that arrays created without explicitly specifying a format will use the new V3 specification. This can cause compatibility issues with older Zarr consumers that only support Zarr format 2.fixIf compatibility with Zarr format 2 is required, explicitly set `zarr_format=2` when creating new arrays, e.g., `zarr.create_array(..., zarr_format=2)`. Also, consider using `zarr.open_array` which can infer the format of existing stores.
affects: >=3.0.0
gotchaConsolidated metadata is a feature in Zarr-Python that aggregates all metadata into a single file for faster access. However, for Zarr format 3, consolidated metadata is currently not part of the official specification. Its use may lead to compatibility issues with other Zarr implementations and its behavior might change in future Zarr-Python versions.fixBe aware that consolidated metadata for Zarr v3 is a Zarr-Python-specific extension. If cross-implementation compatibility or strict adherence to the Zarr v3 spec is critical, consider avoiding consolidated metadata or managing metadata through other means. It is standard for Zarr-Python v2.
affects: All Zarr-Python 3.x versions
gotchaZarr-Python 3 introduces an asynchronous I/O architecture which significantly improves performance, especially with high-latency cloud stores. While a synchronous interface is provided, users with performance-critical cloud workloads may benefit from understanding and leveraging the async APIs.fixFor optimal performance, especially in cloud environments, review the Zarr-Python documentation on asynchronous APIs and concurrency limits. Consider using `async` operations where applicable in your application design.
affects: >=3.0.0
breakingInstallation of Zarr or its core dependency `numcodecs` may fail in minimal environments (like Alpine Linux) due to missing C/C++ build tools. `numcodecs` includes C extensions that require compilation during installation, and without a C compiler (e.g., `gcc`) and Python development headers, the build process will fail.fixEnsure that C/C++ build tools (e.g., `gcc`, `g++`) and Python development headers (e.g., `python3-dev` or `musl-dev` on Alpine) are installed in your environment before attempting to install Zarr or its dependencies.
affects: All
Upgrade
Version history
3.3.0latest on PyPI · released Jul 30, 2026
Audit
Dependencies
numpyrequiredEssential for N-dimensional array operations, as Zarr arrays aim to be NumPy-like.
numcodecsrequiredProvides a variety of compression and filtering codecs used by Zarr.
s3fsoptionalEnables reading and writing Zarr arrays to Amazon S3 (and compatible) object storage.
xarrayoptionalOften used for higher-level data structures (Datasets, DataArrays) that utilize Zarr for backend storage, especially for scientific data.