`xarray.Dataset.rename` does not rename `unlimited_dims`

[damonbayer]

What happened?

If I create a dataset with unlimited_dims, this is overlooked when using xarray.Dataset.rename.

What did you expect to happen?

I would expect for rename to handle renaming the dimension wherever it is relevant.

Minimal Complete Verifiable Example

import xarray as xr
import numpy as np


ds = xr.Dataset({"x": ("y", np.arange(10.0))})
ds.encoding["unlimited_dims"] = ["y"]

ds2 = ds.rename({"y": "y2"})
ds2.to_netcdf("test_unlimited.nc")
# ValueError: Unlimited dimension(s) {'y'} declared in 'dataset.encoding', but not part of current dataset dimensions. Consider removing {'y'} from 'dataset.encoding'.

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

Anything else we need to know?

No response

Environment

Details

NSTALLED VERSIONS

commit: None
python: 3.13.0 (main, Oct 16 2024, 08:05:40) [Clang 18.1.8 ]
python-bits: 64
OS: Darwin
OS-release: 24.6.0
machine: arm64
processor: arm
byteorder: little
LC_ALL: None
LANG: None
LOCALE: ('C', 'UTF-8')
libhdf5: 1.14.6
libnetcdf: None

xarray: 2025.8.0
pandas: 2.3.1
numpy: 2.3.2
scipy: 1.16.0
netCDF4: None
pydap: None
h5netcdf: 1.6.3
h5py: 3.14.0
...
pytest: 8.4.1
mypy: None
IPython: 9.4.0
sphinx: None

[kmuehlbauer]

@damonbayer Thanks for the clear report. Raising errors was a deliberate change in #10608, since in most of the cases a "wrong" declaration of unlimited_dims went by unnoticed by the user. Due to #10647 we've relaxed the ValueError to a UserWarning in #10648 for cases, where the changes are due to xarray machinery. This still will leave you with the mismatch, though.

Regarding encoding please have a look at #1614, #5082 and #6232 and associated issues. TLDR, proper handling of encoding is still in discussion.

[dcherian]

Closing since the general issue of encoding being out-of-date is tracked elsewhere