Install & Compatibility
Where this runs
tested against v0.11.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.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 19.1s · import 2.755s · 399MB
409MB installed
● package 409MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse_url
✓ from ome_zarr.io import parse_url
Writer
✓ from ome_zarr.io import Writer
Reader
✓ from ome_zarr.reader import Reader
write_image
✓ from ome_zarr.writer import write_image
write_multiscale
✓ from ome_zarr.writer import write_multiscale
scale_pyramid
✓ from ome_zarr.scale import scale_pyramid
✗ from ome_zarr.scale import Scaler
`Scaler` class was deprecated in v0.14.0, use `scale_pyramid` function directly.
This quickstart demonstrates how to create a dummy 5D NumPy array, write it to a local OME-Zarr store using `ome_zarr.writer.write_image`, and then read the data and its associated OME metadata back using `ome_zarr.reader.Reader`. It highlights the use of `parse_url` for store creation and the importance of specifying `axes` during writing.
import numpy as np
import zarr
import os
import shutil
from ome_zarr.io import parse_url
from ome_zarr.writer import write_image
from ome_zarr.reader import Reader
# Define a path for the OME-Zarr store
store_path = 'my_ome_zarr_image.zarr'
# Clean up previous store if it exists for a fresh run
if os.path.exists(store_path):
shutil.rmtree(store_path)
# 1. Create a dummy numpy array (e.g., a 5D image: T, C, Z, Y, X)
# OME-Zarr typically uses this dimension order or a subset.
# Here: 1 Time point, 2 Channels, 3 Z-slices, 64 Y, 64 X
data = np.zeros((1, 2, 3, 64, 64), dtype=np.uint16)
data[0, 0, 1, 10:20, 10:20] = 100 # Channel 0, Z-slice 1
data[0, 1, 2, 30:40, 30:40] = 200 # Channel 1, Z-slice 2
# 2. Write the numpy array to an OME-Zarr store
# `parse_url` creates an FSSpec store object.
# `zarr.group` creates the root Zarr group, overwriting if it exists.
storage = parse_url(store_path, mode='w').store
root_group = zarr.group(storage, overwrite=True)
# `write_image` handles the OME-Zarr metadata and array layout.
write_image(
image=data,
group=root_group,
axes=['t', 'c', 'z', 'y', 'x'], # Specify axes order, crucial for OME-Zarr
chunks=(1, 1, 1, 32, 32) # Optional: define Zarr chunking
)
print(f"OME-Zarr image written to: {store_path}")
# 3. Read the OME-Zarr image
reader = Reader(parse_url(store_path))
# Get the list of nodes (images) in the Zarr store. Typically one at the root.
nodes = list(reader())[0]
# Access image data for the highest resolution (level 0)
image_data_level_0 = nodes.data[0]
# Access OME metadata (a dictionary parsed from the OME-XML JSON)
ome_metadata = nodes.metadata
print(f"Successfully read OME-Zarr image from: {store_path}")
print(f"Shape of data (level 0): {image_data_level_0.shape}")
print(f"OME metadata keys: {ome_metadata.keys()}")
# Clean up the created Zarr store (optional but good practice for examples)
shutil.rmtree(store_path)
print(f"Cleaned up: {store_path}")
Debug
Known issues
breakingWriting OME-Zarr versions v0.1, v0.2, and v0.3 was deprecated in v0.15.0 and is no longer supported for new writes.fixEnsure your workflow targets OME-Zarr v0.4 or v0.5 for writing. The library defaults to writing v0.5. If older versions are strictly required, use an `ome-zarr-py` version prior to 0.15.0 or convert externally.
affects: >=0.15.0
deprecatedThe `ome_zarr.scale.Scaler` class was deprecated in v0.14.0.fixInstead of `Scaler()`, use the `ome_zarr.scale.scale_pyramid` function directly for generating multiscale data. For example, `scale_pyramid(data, chunks, max_layer=max_layer, method=method)`.
affects: >=0.14.0
gotchaThe default OME-Zarr specification version for writing changed to v0.5 with `ome-zarr-py` v0.12.0.fixWhile reading is largely backward-compatible, new OME-Zarr stores created will conform to v0.5. Be mindful of this when interoperating with tools that strictly expect an older version. Check the `ome-zarr` metadata within the Zarr store for the exact version being used.
affects: >=0.12.0
gotchaWhen reading or modifying existing Zarr groups, it is best practice to use `zarr.open_group()` instead of `zarr.group()`.fixFor opening an existing Zarr group, always use `zarr.open_group(store_path)` or `zarr.open_group(store)`. Use `zarr.group(store, overwrite=True)` primarily for creating a new root group.
affects: All versions, especially relevant with `zarr` library updates.
gotchaThe `axes` parameter for `write_image` and `write_multiscale` is critical and must accurately reflect the input array's dimensions using OME-Zarr standard axis identifiers.fixAlways explicitly define the `axes` parameter (e.g., `['t', 'c', 'z', 'y', 'x']` or a subset) to match your input array's dimensionality. Incorrect `axes` will lead to malformed OME-Zarr metadata or errors during writing.
affects: *
Errors
Common errors & fixes
AttributeError: module 'zarr' has no attribute 'group'
This error typically indicates an outdated `zarr` library version where `zarr.group` might not be exposed at the top level, or an attempt to use `zarr.group()` in a context where `zarr.open_group()` is expected for an existing store.
fixEnsure your `zarr` library is up-to-date (`pip install --upgrade zarr`). When opening an existing Zarr store or group, prefer `zarr.open_group(store)` over `zarr.group(store)`.
ome_zarr.exceptions.UnsupportedOMEZarrVersionError: The OME-Zarr version '0.1' is not supported for writing.
Attempting to create or update an OME-Zarr store to an older specification version (v0.1, v0.2, v0.3) that is no longer supported for writing by `ome-zarr-py` v0.15.0 and later.
fixAdjust your workflow to write OME-Zarr v0.4 or v0.5. The library will automatically default to v0.5 for new writes. If you need to produce older versions, you'd need an older `ome-zarr-py` installation.
ValueError: image axes must be 't', 'c', 'z', 'y', 'x' or a subset thereof.
The `axes` parameter provided to `write_image` or `write_multiscale` contains invalid characters or does not match the dimensionality of the image data.
fixVerify that your `axes` list exclusively uses the standard OME-Zarr axis identifiers ('t', 'c', 'z', 'y', 'x') and that the number of axes matches the number of dimensions in your input NumPy array. Upgrade
Version history
0.17.0latest on PyPI · released Jun 9, 2026
Audit
Dependencies
zarrrequiredCore Zarr array storage and manipulation.
numpyrequiredFundamental array operations for image data.
numcodecsrequiredCompression and filter codecs for Zarr.
ome-typesrequiredParsing and validating OME metadata.
daskoptionalFor out-of-core and parallel array computations, especially with large datasets.
fsspecoptionalFor accessing various file systems (e.g., S3, Google Cloud Storage).
tifffileoptionalFor converting TIFF files to OME-Zarr.