Registry / data / ome-zarr

ome-zarr

JSON →
library0.17.0pypypi✓ verified 91d ago

ome-zarr is a Python library providing an implementation of images in Zarr files according to the OME-Zarr specification. It enables reading and writing bioimaging data stored in the OME-Zarr format, supporting multiscale images, metadata, and various Zarr features like chunking and compression. The current version is 0.16.0, with a release cadence that sees new features and bug fixes approximately every few months, often tied to updates in the OME-Zarr specification itself.

pip install ome-zarr
INSTALL
IMPORT
SIG · OME-ZARR
O
ome-zarr
datapythonv0.17.0
Install
19.1s avg
Import
2755ms
Disk
409MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.9–3.13
musl
3.9–3.13
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
musl
py 3.10–3.920 runs
build_error
glibc
py 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.
fix
Ensure 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.
fix
Instead 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.
fix
While 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()`.
fix
For 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.
fix
Always 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.
fix
Ensure 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.
fix
Adjust 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.
fix
Verify 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.
Agent activity
24 hits · last 30 days
node
22
Resources
ome-zarr — pip install ome-zarr · libregistry