Dataset.to_zarr() - unexpected keyword zarr_format

[jameshod5]

What happened?

As per the documentation, we are moving away from using zarr_version and instead using zarr_format. When making this switch, many of our tests fail because of the error:

TypeError: Dataset.to_zarr() got an unexpected keyword argument 'zarr_format'

What did you expect to happen?

We expected the functionality of Dataset.to_zarr() to not change from changing these args

Minimal Complete Verifiable Example

import xarray as xr
import numpy as np

ds = xr.Dataset(
    {
        "temperature": (("x", "y"), np.random.rand(4, 3))
    },
    coords={
        "x": [0, 1, 2, 3],
        "y": [10, 20, 30]
    },
    attrs={"description": "Simple test dataset"}
)

# Save to a Zarr file using Zarr v3 format
ds.to_zarr("example_zarr.zarr", mode="w", zarr_format=3)

MVCE confirmation

• Minimal example — the example is as focused as reasonably possible to demonstrate the underlying issue in xarray.
• Complete example — the example is self-contained, including all data and the text of any traceback.
• Verifiable example — the example copy & pastes into an IPython prompt or Binder notebook, returning the result.
• New issue — a search of GitHub Issues suggests this is not a duplicate.
• Recent environment — the issue occurs with the latest version of xarray and its dependencies.

Relevant log output

def _write_single_zarr(self, file_name: str, name: str, dataset: xr.Dataset):
        file_name = self.output_path / file_name
>       dataset.to_zarr(
            file_name, group=name, mode="w", zarr_format=self.version, consolidated=True
        )
E       TypeError: Dataset.to_zarr() got an unexpected keyword argument 'zarr_format'

src/core/writer.py:75: TypeError

Anything else we need to know?

No response

Environment

INSTALLED VERSIONS

commit: None
python: 3.12.6 (main, Sep 9 2024, 21:36:32) [Clang 18.1.8 ]
python-bits: 64
OS: Darwin
OS-release: 23.6.0
machine: arm64
processor: arm
byteorder: little
LC_ALL: None
LANG: None
LOCALE: (None, 'UTF-8')
libhdf5: 1.14.6
libnetcdf: None

xarray: 2024.7.0
pandas: 2.2.3
numpy: 2.0.2
scipy: 1.13.1
netCDF4: None
pydap: None
h5netcdf: 1.6.1
h5py: 3.13.0
zarr: 3.0.6
cftime: None
nc_time_axis: None
iris: None
bottleneck: 1.4.2
dask: 2024.8.0
distributed: 2024.8.0
matplotlib: None
cartopy: None
seaborn: None
numbagg: None
fsspec: 2025.3.2
cupy: None
pint: 0.24.4
sparse: None
flox: None
numpy_groupies: None
setuptools: None
pip: None
conda: None
pytest: 8.3.5
mypy: None
IPython: 9.1.0
sphinx: None

[welcome]

Thanks for opening your first issue here at xarray! Be sure to follow the issue template!
If you have an idea for a solution, we would really welcome a Pull Request with proposed changes.
See the Contributing Guide for more.
It may take us a while to respond here, but we really value your contribution. Contributors like you help make xarray better.
Thank you!

[VeckoTheGecko]

From the docs:

zarr_version (int or None, optional) – .. deprecated:: 2024.9.1 Use zarr_format instead.

Looks like zarr_format was added in 2024.9.1, but you're running an earlier version (2024.7.1). zarr_version should work (but will throw a deprecation warning from zarr)

[VeckoTheGecko]

This seems to be a duplicate of #10163

[keewis]

no, #10163 is about DataArray.to_zarr, which had gone out of sync, while this one's about Dataset.to_zarr.

I agree with your analysis, though (most of it, it's xarray that's emitting the deprecation warning): zarr_version has been deprecated the moment zarr_format was introduced. However, unlike what the docs are claiming, this was in 2024.10.0; there is no 2024.09.1. PRs to fix that welcome!

@jameshod5, could you try upgrading xarray to at least 2024.10.0 and report back if this still throws an error?

[jameshod5]

Thanks both, it looks like that upgrading xarray to 2024.10.0 has fixed the issue. Apologies!