`anndata.io.read_zarr` incompatible with a Zarr ZipStorage

[WeilerP]

Please make sure these conditions are met

• I have checked that this issue has not already been reported.
• I have confirmed this bug exists on the latest version of anndata.
• (optional) I have confirmed this bug exists on the main branch of anndata.

Report

Previously, anndata.io.read_zarr read from a Zarr ZipStorage, i.e.,

import numpy as np
import anndata as ad
import zarr

adata = AnnData(np.eye(3))

store = zarr.storage.ZipStore("dummy.zarr.zip", mode="w")
adata.write_zarr(store=store)
store.close()

adata = ad.read_zarr("dummy.zarr.zip")

previously worked, but now fails with

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/.conda/envs/ad-py312/lib/python3.12/site-packages/anndata/_io/zarr.py", line 75, in read_zarr
    f = store if isinstance(store, zarr.Group) else zarr.open(store, mode="r")
                                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/.conda/envs/ad-py312/lib/python3.12/site-packages/zarr/api/synchronous.py", line 209, in open
    obj = sync(
          ^^^^^
  File "/.conda/envs/ad-py312/lib/python3.12/site-packages/zarr/core/sync.py", line 163, in sync
    raise return_result
  File "/.conda/envs/ad-py312/lib/python3.12/site-packages/zarr/core/sync.py", line 119, in _runner
    return await coro
           ^^^^^^^^^^
  File "/.conda/envs/ad-py312/lib/python3.12/site-packages/zarr/api/asynchronous.py", line 386, in open
    return await open_group(store=store_path, zarr_format=zarr_format, mode=mode, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/.conda/envs/ad-py312/lib/python3.12/site-packages/zarr/api/asynchronous.py", line 872, in open_group
    raise GroupNotFoundError(msg)
zarr.errors.GroupNotFoundError: No group found in store StorePath(LocalStore, 'dummy.zarr.zip') at path ''

Is this change intentional? Specifying the Zarr store directly works, i.e.,

store = zarr.storage.ZipStore("dummy.zarr.zip:, mode="r")
adata = ad.io.read_zarr(store)
store.close()

Versions

| Package | Version |
| ------- | ------- |
| numpy   | 2.3.3   |
| anndata | 0.12.2  |
| zarr    | 3.1.3   |

| Dependency         | Version     |
| ------------------ | ----------- |
| h5py               | 3.15.0      |
| numcodecs          | 0.16.3      |
| pandas             | 2.3.3       |
| legacy-api-wrap    | 1.4.1       |
| session-info2      | 0.2.3       |
| dfo                | 0.0.0       |
| packaging          | 25.0        |
| natsort            | 8.4.0       |
| scipy              | 1.16.2      |
| donfig             | 0.8.1.post1 |
| python-dateutil    | 2.9.0.post0 |
| setuptools         | 80.9.0      |
| crc32c             | 2.7.1.post0 |
| pytz               | 2025.2      |
| PyYAML             | 6.0.3       |
| six                | 1.17.0      |
| scanpy             | 1.11.4      |
| typing_extensions  | 4.15.0      |
| pyarrow            | 21.0.0      |
| charset-normalizer | 3.4.4       |

| Component | Info                                                                           |
| --------- | ------------------------------------------------------------------------------ |
| Python    | 3.12.12 | packaged by conda-forge | (main, Oct 13 2025, 14:34:15) [GCC 14.3.0] |
| OS        | Linux-4.18.0-425.19.2.el8_7.x86_64-x86_64-with-glibc2.28                       |
| Updated   | 2025-10-14 12:55                                                               |

[ilan-gold]

I think this is intentional - previously zarr handled this for us:

https://github.com/scverse/anndata/blob/0.11.x/src/anndata/_io/zarr.py#L70

We weren't actually doing any special handling. I am generally against "magic strings" and ending something with ".zip" feels like a magic string. If you wanted you could open this with zarr and see if they're interested but for us, if you wanted a PR to handle this again, it would have to wait until 0.13 because this would be another breaking change.

I'm not against it, but hesitant. I really like zarr stores and think they make things super clear as to what you're doing.

[flying-sheep]

I agree with you @ilan-gold. For convenience, we could add a nice note:

potential_stores = {
    ".zip": "zarr.storage.ZipStore",
}

def read_zarr(store: os.PathLike[str] | str | ...) -> AnnData:
    try:
        return _read_zarr_inner(store)
    except GroupNotFoundError as e:
        if isinstance(store, os.PathLike | str) and cls_name := potential_stores.get(Path(store).suffix):
            e.add_note(f"Did you mean `read_zarr({cls_name}({os.fspath(store)!r}))`?")
    raise

[WeilerP]

Yes, I understand and agree with not blindly relying on an inferred file extension, but if you already introduce a try and except, why not try reading from a ZipStore if the file ends on ".zip"? Or add a flag zip_store to the read_zarr function; similarly, you could add a flag to write_zarr like the compression argument in write_h5ad (in reference to #1971).