In open_zarr, decode_timedelta does not behave as documented

[theo-xirouchaki]

What happened?

The documentation states that, for open_zarr, if decode_timedelta is None it will take the value of decode_times which is True by default. That isn't the behaviour I'm seeing, timedeltas are not being decoded.

What did you expect to happen?

I expected timedeltas to be decoded.

Minimal Complete Verifiable Example

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "xarray[complete]@git+https://github.com/pydata/xarray.git@main",
# ]
# ///
#
# This script automatically imports the development branch of xarray to check for issues.
# Please delete this header if you have _not_ tested this script with `uv run`!

import xarray as xr
xr.show_versions()
# your reproducer code ...
xr.open_zarr('gs://weatherbench2/datasets/hres/2016-2022-0012-1440x721.zarr',storage_options={"token": "anon"}, decode_times=True, decode_timedelta=None)

Steps to reproduce

In a conda environment with xarray 2026.7.0, zarr 3.3.0, fsspec 2026.6.0 and gcsfs 2026.7.0, run the following code:
xr.open_zarr('gs://weatherbench2/datasets/hres/2016-2022-0012-1440x721.zarr',storage_options={"token": "anon"}, decode_times=True, decode_timedelta=None)

It returns a dataset with the timedeltas not decoded.

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

<xarray.Dataset> Size: 87TB
Dimensions:                   (time: 5134, prediction_timedelta: 41,
                               latitude: 721, longitude: 1440, level: 13)
Coordinates:
  * time                      (time) datetime64[ns] 41kB 2016-01-01 ... 2023-...
  * prediction_timedelta      (prediction_timedelta) int64 328B 0 6 ... 234 240
  * latitude                  (latitude) float32 3kB -90.0 -89.75 ... 89.75 90.0
  * longitude                 (longitude) float32 6kB 0.0 0.25 ... 359.5 359.8
  * level                     (level) int32 52B 50 100 150 200 ... 850 925 1000
Data variables: (12/16)
    10m_u_component_of_wind   (time, prediction_timedelta, latitude, longitude) float32 874GB ...
    10m_v_component_of_wind   (time, prediction_timedelta, latitude, longitude) float32 874GB ...
    10m_wind_speed            (time, prediction_timedelta, latitude, longitude) float32 874GB ...
    2m_temperature            (time, prediction_timedelta, latitude, longitude) float32 874GB ...
    geopotential              (time, prediction_timedelta, level, latitude, longitude) float32 11TB ...
    mean_sea_level_pressure   (time, prediction_timedelta, latitude, longitude) float32 874GB ...
    ...                        ...
    total_precipitation_24hr  (time, prediction_timedelta, latitude, longitude) float32 874GB ...
    total_precipitation_6hr   (time, prediction_timedelta, latitude, longitude) float32 874GB ...
    u_component_of_wind       (time, prediction_timedelta, level, latitude, longitude) float32 11TB ...
    v_component_of_wind       (time, prediction_timedelta, level, latitude, longitude) float32 11TB ...
    vertical_velocity         (time, prediction_timedelta, level, latitude, longitude) float32 11TB ...
    wind_speed                (time, prediction_timedelta, level, latitude, longitude) float32 11TB ...

Anything else we need to know?

No response

Environment

Details

INSTALLED VERSIONS

commit: None
python: 3.14.6 | packaged by conda-forge | (main, Jul 24 2026, 16:09:24) [GCC 14.3.0]
python-bits: 64
OS: Linux
OS-release: 5.14.0-687.30.1.el9_8.x86_64
machine: x86_64
processor: x86_64
byteorder: little
LC_ALL: None
LANG: en_GB.UTF-8
LOCALE: ('en_GB', 'UTF-8')
libhdf5: None
libnetcdf: None

xarray: 2026.7.0
pandas: 3.0.5
numpy: 2.5.2
scipy: None
netCDF4: None
pydap: None
h5netcdf: None
h5py: None
zarr: 3.3.0
cftime: None
nc_time_axis: None
iris: None
bottleneck: None
dask: None
distributed: None
matplotlib: None
cartopy: None
seaborn: None
numbagg: None
fsspec: 2026.6.0
cupy: None
pint: None
sparse: None
flox: None
numpy_groupies: None
setuptools: None
pip: 26.2.1
conda: None
pytest: None
mypy: None
IPython: None
sphinx: None

[dcherian]

Thanks, we would take a PR to fix this

[theo-xirouchaki]

Unfortunately I don't have the capacity to work out a fix right now but I hope someone picks it up

[sahilmathur254]

I can take this. I’ll first reduce the remote example to a small local Zarr fixture, then add regression coverage for decode_timedelta=None inheriting from both decode_times=True and decode_times=False, while preserving explicit decode_timedelta=True and decode_timedelta=False overrides. I’ll keep the implementation scoped to resolving that option consistently before the Zarr decode path. Unless there’s a backend-specific compatibility constraint I’m missing, I’ll proceed with that scope.

[kmuehlbauer]

Please have a look at #1621 and related PR's beforehand.

[sahilmathur254]

Thanks for the pointer. I reviewed #1621 and the related merged PRs, particularly #4071, #9966, #10101, and #11173. PR #11173 intentionally changed decode_timedelta=None so units-only variables are no longer decoded by default, while explicit decode_timedelta=True remains the opt-in path and dtype-tagged timedeltas continue to round-trip.

That suggests the current open_zarr behaviour is intentional and the documentation is stale. The same outdated “assume the value of decode_times” wording also appears across the related opening APIs. I can revise the scope to correct those docstrings and add focused coverage distinguishing decode_timedelta=None from decode_timedelta=True.

Does that match the intended fix, or should open_zarr behave differently from the contract introduced in #11173?

[kmuehlbauer]

Thanks for cross-checking @sahilmathur254. Yes, documentation seems to be stale here. I'm no zarr expert, but I'm assuming that it is same for all open functions, that decode_times and decode_timedelta should be decoupled.

[sahilmathur254]

I found one remaining behaviour to confirm before preparing the patch: decode_cf_variable currently resolves decode_timedelta=None to False when decode_times=False. As a result, dtype-tagged timedelta variables are decoded by default when decode_times=True, but not when decode_times=False.
To fully decouple them, I propose resolving decode_timedelta=None to a default CFTimedeltaCoder() independently of a boolean decode_times value. I would then update the opening-function docstrings and add coverage for units-only values, dtype-tagged values, and explicit decode_timedelta=True / decode_timedelta=False overrides.
One detail: when decode_times is a CFDatetimeCoder, should decode_timedelta=None continue inheriting its time_unit, as introduced in #9966, or should the timedelta coder now be entirely independent?