Command-line interface#

Zarr-Python provides a command-line interface that enables:

  • migration of Zarr v2 metadata to v3

  • removal of v2 or v3 metadata

To see available commands run the following in a terminal:

$ zarr --help

or to get help on individual commands:

$ zarr migrate --help

$ zarr remove-metadata --help

Migrate metadata from v2 to v3#

Migrate to a separate location#

To migrate a Zarr array/group’s metadata from v2 to v3 run:

$ zarr migrate v3 path/to/input.zarr path/to/output.zarr

This will write new zarr.json files to output.zarr, leaving input.zarr un-touched. Note - this will migrate the entire Zarr hierarchy, so if input.zarr contains multiple groups/arrays, new zarr.json will be made for all of them.

Migrate in-place#

If you’d prefer to migrate the metadata in-place run:

$ zarr migrate v3 path/to/input.zarr

This will write new zarr.json files to input.zarr, leaving the existing v2 metadata un-touched.

To open the array/group using the new metadata use:

>>> import zarr
>>> zarr_with_v3_metadata = zarr.open('path/to/input.zarr', zarr_format=3)

Once you are happy with the conversion, you can run the following to remove the old v2 metadata:

$ zarr remove-metadata v2 path/to/input.zarr

Note there is also a shortcut to migrate and remove v2 metadata in one step:

$ zarr migrate v3 path/to/input.zarr --remove-v2-metadata

Remove metadata#

Remove v2 metadata using:

$ zarr remove-metadata v2 path/to/input.zarr

or v3 with:

$ zarr remove-metadata v3 path/to/input.zarr

By default, this will only allow removal of metadata if a valid alternative exists. For example, you can’t remove v2 metadata unless v3 metadata exists at that location.

To override this behaviour use --force:

$ zarr remove-metadata v3 path/to/input.zarr --force

Dry run#

All commands provide a --dry-run option that will log changes that would be made on a real run, without creating or modifying any files.

$ zarr migrate v3 path/to/input.zarr --dry-run

Dry run enabled - no new files will be created or changed. Log of files that would be created on a real run:
Saving metadata to path/to/input.zarr/zarr.json

Verbose#

You can also add --verbose before any command, to see a full log of its actions:

$ zarr --verbose migrate v3 path/to/input.zarr

$ zarr --verbose remove-metadata v2 path/to/input.zarr

Equivalent functions#

All features of the command-line interface are also available via functions under zarr.metadata.