Skip to content

Improve store section in migration guide #3552

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Nov 17, 2025
+21 −24
Merged

Improve store section in migration guide #3552

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d37820a
Improve store section in migration guide
dstansby Oct 27, 2025
2056e28
Update docs/user-guide/v3_migration.md
dstansby Oct 27, 2025
6d65136
Merge branch 'main' into migration-store-guide
d-v-b Nov 17, 2025
d14c426
Merge branch 'main' into migration-store-guide
d-v-b Nov 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 21 additions & 24 deletions docs/user-guide/v3_migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,51 +117,48 @@ The following sections provide details on breaking changes in Zarr-Python 3.

### The Store class

The Store API has changed significant in Zarr-Python 3. The most notable changes to the
Store API are:
The Store API has changed significant in Zarr-Python 3.

#### Store Import Paths
#### The base store class

Several store implementations have moved from the top-level module to `zarr.storage`:
The `MutableMapping` base class has been replaced in favor of a custom abstract base class ([`zarr.abc.store.Store`][]).
An asynchronous interface is used for all store methods that use I/O.
This change ensures that all store methods are non-blocking and are as performant as possible.

#### Store implementations

Store implementations have moved from the top-level module to `zarr.storage`:

```diff title="Store import changes from v2 to v3"
# Before (v2)
- from zarr import MemoryStore, DirectoryStore
+ from zarr.storage import MemoryStore, LocalStore # LocalStore replaces DirectoryStore
- from zarr import MemoryStore
+ from zarr.storage import MemoryStore
```

Common replacements:
The following stores have been renamed or changed:

| v2 Import | v3 Import |
|-------------------------|------------------------------------|
| `zarr.MemoryStore` | [`zarr.storage.MemoryStore`][] |
| `zarr.DirectoryStore` | [`zarr.storage.LocalStore`][] |
| `zarr.TempStore` | Use [`tempfile.TemporaryDirectory`][] with [`LocalStore`][zarr.storage.LocalStore] |
| v2 | v3 |
|------------------------|------------------------------------|
| `DirectoryStore` | [`zarr.storage.LocalStore`][] |
| `FSStore` | [`zarr.storage.FsspecStore`][] |
| `TempStore` | Use [`tempfile.TemporaryDirectory`][] with [`LocalStore`][zarr.storage.LocalStore] |
| `zarr.
Copy link
Contributor

@QuLogic QuLogic Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something seems to have broken here; this table line and the cross-reference are incomplete.


1. Replaced the `MutableMapping` base class in favor of a custom abstract base class
([`zarr.abc.store.Store`][]).
2. Switched to an asynchronous interface for all store methods that result in IO. This
change ensures that all store methods are non-blocking and are as performant as
possible.

Beyond the changes store interface, a number of deprecated stores were also removed in
Zarr-Python 3. See issue #1274 for more details on the removal of these stores.
A number of deprecated stores were also removed.
See issue #1274 for more details on the removal of these stores.

- `N5Store` - see https://github.com/zarr-developers/n5py for an alternative interface to
N5 formatted data.
- `ABSStore` - use the [`zarr.storage.FsspecStore`][] instead along with fsspec's
[adlfs backend](https://github.com/fsspec/adlfs).

The following stores have been removed altogether. Users who need these stores will have to
implement their own version in zarr-python v3.

- `DBMStore`
- `LMDBStore`
- `SQLiteStore`
- `MongoDBStore`
- `RedisStore`

At present, the latter five stores in this list do not have an equivalent in Zarr-Python 3.
The latter five stores in this list do not have an equivalent in Zarr-Python 3.
If you are interested in developing a custom store that targets these backends, see
[developing custom stores](storage.md/#developing-custom-stores) or open an
[issue](https://github.com/zarr-developers/zarr-python/issues) to discuss your use case.
Expand Down