zarr-developers · maxrjones · Apr 7, 2026 · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -61,7 +61,7 @@ body:
       value: |
         ```python
         # /// script
-        # requires-python = ">=3.11"
+        # requires-python = ">=3.12"
         # dependencies = [
         #   "zarr@git+https://github.com/zarr-developers/zarr-python.git@main",
         # ]

diff --git a/.github/workflows/gpu_test.yml b/.github/workflows/gpu_test.yml
@@ -27,7 +27,7 @@ jobs:
     runs-on: gpu-runner
     strategy:
       matrix:
-        python-version: ['3.11']
+        python-version: ['3.12']
 
     steps:
     - uses: actions/checkout@v6

diff --git a/.github/workflows/nightly_wheels.yml b/.github/workflows/nightly_wheels.yml
@@ -23,7 +23,7 @@ jobs:
       - uses: actions/setup-python@v6
         name: Install Python
         with:
-          python-version: '3.13'
+          python-version: '3.14'
 
       - name: Install Hatch
         uses: pypa/hatch@257e27e51a6a5616ed08a39a408a21c35c9931bc

diff --git a/.github/workflows/releases.yml b/.github/workflows/releases.yml
@@ -31,7 +31,7 @@ jobs:
       - uses: actions/setup-python@v6
         name: Install Python
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install Hatch
         uses: pypa/hatch@257e27e51a6a5616ed08a39a408a21c35c9931bc

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -23,23 +23,23 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ['3.11', '3.12', '3.13']
+        python-version: ['3.12', '3.13', '3.14']
         dependency-set: ["minimal", "optional"]
         os: ["ubuntu-latest"]
         include:
-          - python-version: '3.11'
+          - python-version: '3.12'
             dependency-set: 'optional'
             os: 'macos-latest'
 
-          - python-version: '3.13'
+          - python-version: '3.14'
             dependency-set: 'optional'
             os: 'macos-latest'
 
-          - python-version: '3.11'
+          - python-version: '3.12'
             dependency-set: 'optional'
             os: 'windows-latest'
 
-          - python-version: '3.13'
+          - python-version: '3.14'
             dependency-set: 'optional'
             os: 'windows-latest'
     runs-on: ${{ matrix.os }}
@@ -79,12 +79,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.11', "3.13"]
+        python-version: ['3.12', "3.14"]
         dependency-set: ["upstream", "min_deps"]
         exclude:
-          - python-version: "3.13"
+          - python-version: "3.14"
             dependency-set: min_deps
-          - python-version: "3.11"
+          - python-version: "3.12"
             dependency-set: upstream
     steps:
     - uses: actions/checkout@v6

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -7,7 +7,7 @@ ci:
 default_stages: [pre-commit, pre-push]
 
 default_language_version:
-  python: python3.11
+  python: python3.12
 
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
@@ -38,7 +38,7 @@ repos:
           - donfig
           - numcodecs
           - google-crc32c>=1.5
-          - numpy==2.1 # until https://github.com/numpy/numpy/issues/28034 is resolved
+          - numpy==2.1 # https://github.com/zarr-developers/zarr-python/issues/3780 + https://github.com/zarr-developers/zarr-python/issues/3688
           - typing_extensions
           - universal-pathlib
           - obstore>=0.5.1

diff --git a/changes/3546.misc.md b/changes/3546.misc.md
@@ -0,0 +1 @@
+Upgrade to spec0 compat (python 3.14 max, python 3.12 min).
diff --git a/changes/3830.misc.md b/changes/3830.misc.md
@@ -0,0 +1 @@
+Optimize the performance of indexing operations when using an array-like indexer on a single dimension.
diff --git a/changes/3833.misc.md b/changes/3833.misc.md
@@ -0,0 +1 @@
+Remove the warning that is emitted when any Numcodecs codec is instantiated.
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -205,7 +205,7 @@ When submitting a pull request, coverage will also be collected across all suppo
 
 ### Documentation
 
-Docstrings for user-facing classes and functions should follow the [numpydoc](https://numpydoc.readthedocs.io/en/stable/format.html#docstring-standard) standard, including sections for Parameters and Examples. All examples should run and pass as doctests under Python 3.11.
+Docstrings for user-facing classes and functions should follow the [numpydoc](https://numpydoc.readthedocs.io/en/stable/format.html#docstring-standard) standard, including sections for Parameters and Examples. All examples should run and pass as doctests under Python 3.12.
 
 Zarr uses mkdocs for documentation, hosted on readthedocs.org. Documentation is written in the Markdown markup language (.md files) in the `docs` folder. The documentation consists both of prose and API documentation. All user-facing classes and functions are included in the API documentation, under the `docs/api` folder using the [mkdocstrings](https://mkdocstrings.github.io/) extension. Add any new public functions or classes to the relevant markdown file in `docs/api/*.md`. Any new features or important usage information should be included in the user-guide (`docs/user-guide`). Any changes should also be included as a new file in the `changes` directory.
 

diff --git a/docs/design/chunk-grid.md b/docs/design/chunk-grid.md
diff --git a/docs/index.md b/docs/index.md
@@ -21,7 +21,7 @@ Zarr-Python is a Python library for reading and writing Zarr groups and arrays.
 
 ## Installation
 
-Zarr requires Python 3.11 or higher. You can install it via `pip`:
+Zarr requires Python 3.12 or higher. You can install it via `pip`:
 
 ```bash
 pip install zarr

diff --git a/docs/user-guide/arrays.md b/docs/user-guide/arrays.md
@@ -599,6 +599,171 @@ In this example a shard shape of (1000, 1000) and a chunk shape of (100, 100) is
 This means that `10*10` chunks are stored in each shard, and there are `10*10` shards in total.
 Without the `shards` argument, there would be 10,000 chunks stored as individual files.
 
+## Rectilinear (variable) chunk grids
+
+!!! warning "Experimental"
+    Rectilinear chunk grids are an experimental feature and may change in
+    future releases. This feature is expected to stabilize in Zarr version 3.3.
+
+    Because the feature is still stabilizing, it is disabled by default and
+    must be explicitly enabled:
+
+    ```python
+    import zarr
+    zarr.config.set({"array.rectilinear_chunks": True})
+    ```
+
+    Or via the environment variable `ZARR_ARRAY__RECTILINEAR_CHUNKS=True`.
+
+    The examples below assume this config has been set.
+
+By default, Zarr arrays use a regular chunk grid where every chunk along a
+given dimension has the same size (except possibly the final boundary chunk).
+Rectilinear chunk grids allow each chunk along a dimension to have a different
+size. This is useful when the natural partitioning of the data is not uniform —
+for example, satellite swaths of varying width, time series with irregular
+intervals, or spatial tiles of different extents.
+
+### Creating arrays with rectilinear chunks
+
+To create an array with rectilinear chunks, pass a nested list to the `chunks`
+parameter where each inner list gives the chunk sizes along one dimension:
+
+```python exec="true" session="arrays" source="above" result="ansi"
+zarr.config.set({"array.rectilinear_chunks": True})
+z = zarr.create_array(
+    store=zarr.storage.MemoryStore(),
+    shape=(60, 100),
+    chunks=[[10, 20, 30], [50, 50]],
+    dtype='int32',
+)
+print(z.info)
+```
+
+In this example the first dimension is split into three chunks of sizes 10, 20,
+and 30, while the second dimension is split into two equal chunks of size 50.
+
+### Reading and writing data
+
+Rectilinear arrays support the same indexing interface as regular arrays.
+Reads and writes that cross chunk boundaries of different sizes are handled
+automatically:
+
+```python exec="true" session="arrays" source="above" result="ansi"
+import numpy as np
+data = np.arange(60 * 100, dtype='int32').reshape(60, 100)
+z[:] = data
+# Read a slice that spans the first two chunks (sizes 10 and 20) along axis 0
+print(z[5:25, 0:5])
+```
+
+### Inspecting chunk sizes
+
+The `.write_chunk_sizes` property returns the actual data size of each storage
+chunk along every dimension. It works for both regular and rectilinear arrays
+and returns a tuple of tuples (matching the dask `Array.chunks` convention).
+When sharding is used, `.read_chunk_sizes` returns the inner chunk sizes instead:
+
+```python exec="true" session="arrays" source="above" result="ansi"
+print(z.write_chunk_sizes)
+```
+
+For regular arrays, this includes the boundary chunk:
+
+```python exec="true" session="arrays" source="above" result="ansi"
+z_regular = zarr.create_array(
+    store=zarr.storage.MemoryStore(),
+    shape=(100, 80),
+    chunks=(30, 40),
+    dtype='int32',
+)
+print(z_regular.write_chunk_sizes)
+```
+
+Note that the `.chunks` property is only available for regular chunk grids. For
+rectilinear arrays, use `.write_chunk_sizes` (or `.read_chunk_sizes`) instead.
+
+### Resizing and appending
+
+Rectilinear arrays can be resized. When growing past the current edge sum, a
+new chunk is appended covering the additional extent. When shrinking, the chunk
+edges are preserved and the extent is re-bound (chunks beyond the new extent
+simply become inactive):
+
+```python exec="true" session="arrays" source="above" result="ansi"
+z = zarr.create_array(
+    store=zarr.storage.MemoryStore(),
+    shape=(30,),
+    chunks=[[10, 20]],
+    dtype='float64',
+)
+z[:] = np.arange(30, dtype='float64')
+print(f"Before resize: chunk_sizes={z.write_chunk_sizes}")
+z.resize((50,))
+print(f"After resize:  chunk_sizes={z.write_chunk_sizes}")
+```
+
+The `append` method also works with rectilinear arrays:
+
+```python exec="true" session="arrays" source="above" result="ansi"
+z.append(np.arange(10, dtype='float64'))
+print(f"After append:  shape={z.shape}, chunk_sizes={z.write_chunk_sizes}")
+```
+
+### Compressors and filters
+
+Rectilinear arrays work with all codecs — compressors, filters, and checksums.
+Since each chunk may have a different size, the codec pipeline processes each
+chunk independently:
+
+```python exec="true" session="arrays" source="above" result="ansi"
+z = zarr.create_array(
+    store=zarr.storage.MemoryStore(),
+    shape=(60, 100),
+    chunks=[[10, 20, 30], [50, 50]],
+    dtype='float64',
+    filters=[zarr.codecs.TransposeCodec(order=(1, 0))],
+    compressors=[zarr.codecs.BloscCodec(cname='zstd', clevel=3)],
+)
+z[:] = np.arange(60 * 100, dtype='float64').reshape(60, 100)
+np.testing.assert_array_equal(z[:], np.arange(60 * 100, dtype='float64').reshape(60, 100))
+print("Roundtrip OK")
+```
+
+### Rectilinear shard boundaries
+
+Rectilinear chunk grids can also be used for shard boundaries when combined
+with sharding. In this case, the outer grid (shards) is rectilinear while the
+inner chunks remain regular. Each shard dimension must be divisible by the
+corresponding inner chunk size:
+
+```python exec="true" session="arrays" source="above" result="ansi"
+z = zarr.create_array(
+    store=zarr.storage.MemoryStore(),
+    shape=(120, 100),
+    chunks=(10, 10),
+    shards=[[60, 40, 20], [50, 50]],
+    dtype='int32',
+)
+z[:] = np.arange(120 * 100, dtype='int32').reshape(120, 100)
+print(z[50:70, 40:60])
+```
+
+Note that rectilinear inner chunks with sharding are not supported — only the
+shard boundaries can be rectilinear.
+
+### Metadata format
+
+Rectilinear chunk grid metadata uses run-length encoding (RLE) for compact
+serialization. When reading metadata, both bare integers and `[value, count]`
+pairs are accepted:
+
+- `[10, 20, 30]` — three chunks with explicit sizes
+- `[[10, 3]]` — three chunks of size 10 (RLE shorthand)
+- `[[10, 3], 5]` — three chunks of size 10, then one chunk of size 5
+
+When writing, Zarr automatically compresses repeated values into RLE format.
+
 ## Missing features in 3.0
 
 The following features have not been ported to 3.0 yet.

diff --git a/docs/user-guide/config.md b/docs/user-guide/config.md
@@ -30,6 +30,7 @@ Configuration options include the following:
 - Default Zarr format `default_zarr_version`
 - Default array order in memory `array.order`
 - Whether empty chunks are written to storage `array.write_empty_chunks`
+- Enable experimental rectilinear chunk grids `array.rectilinear_chunks`
 - Async and threading options, e.g. `async.concurrency` and `threading.max_workers`
 - Selections of implementations of codecs, codec pipelines and buffers
 - Enabling GPU support with `zarr.config.enable_gpu()`. See GPU support for more.

diff --git a/docs/user-guide/installation.md b/docs/user-guide/installation.md
@@ -4,7 +4,7 @@
 
 Required dependencies include:
 
-- [Python](https://docs.python.org/3/) (3.11 or later)
+- [Python](https://docs.python.org/3/) (3.12 or later)
 - [packaging](https://packaging.pypa.io) (22.0 or later)
 - [numpy](https://numpy.org) (2.0 or later)
 - [numcodecs](https://numcodecs.readthedocs.io) (0.14 or later)

diff --git a/docs/user-guide/v3_migration.md b/docs/user-guide/v3_migration.md
@@ -198,32 +198,29 @@ after the 3.0.0 release. If features listed below are important to your use case
 of Zarr-Python, please open (or comment on) a
 [GitHub issue](https://github.com/zarr-developers/zarr-python/issues/new).
 
-- The following functions / methods have not been ported to Zarr-Python 3 yet:
+The following functions / methods have not been ported to Zarr-Python 3 yet:
 
-  * `zarr.copy` ([issue #2407](https://github.com/zarr-developers/zarr-python/issues/2407))
-  * `zarr.copy_all` ([issue #2407](https://github.com/zarr-developers/zarr-python/issues/2407))
-  * `zarr.copy_store` ([issue #2407](https://github.com/zarr-developers/zarr-python/issues/2407))
-  * `zarr.Group.move` ([issue #2108](https://github.com/zarr-developers/zarr-python/issues/2108))
+- `zarr.copy` ([issue #2407](https://github.com/zarr-developers/zarr-python/issues/2407))
+- `zarr.copy_all` ([issue #2407](https://github.com/zarr-developers/zarr-python/issues/2407))
+- `zarr.copy_store` ([issue #2407](https://github.com/zarr-developers/zarr-python/issues/2407))
+- `zarr.Group.move` ([issue #2108](https://github.com/zarr-developers/zarr-python/issues/2108))
 
-- The following features (corresponding to function arguments to functions in
+The following features (corresponding to function arguments to functions in
   `zarr`) have not been ported to Zarr-Python 3 yet. Using these features
   will raise a warning or a `NotImplementedError`:
 
-  * `cache_attrs`
-  * `cache_metadata`
-  * `chunk_store` ([issue #2495](https://github.com/zarr-developers/zarr-python/issues/2495))
-  * `meta_array`
-  * `object_codec` ([issue #2617](https://github.com/zarr-developers/zarr-python/issues/2617))
-  * `synchronizer` ([issue #1596](https://github.com/zarr-developers/zarr-python/issues/1596))
-  * `dimension_separator`
+- `cache_attrs`
+- `cache_metadata`
+- `chunk_store` ([issue #2495](https://github.com/zarr-developers/zarr-python/issues/2495))
+- `meta_array`
+- `object_codec` ([issue #2617](https://github.com/zarr-developers/zarr-python/issues/2617))
+- `synchronizer` ([issue #1596](https://github.com/zarr-developers/zarr-python/issues/1596))
+- `dimension_separator`
 
-- The following features that were supported by Zarr-Python 2 have not been ported
+The following features that were supported by Zarr-Python 2 have not been ported
   to Zarr-Python 3 yet:
 
-  * Structured arrays / dtypes ([issue #2134](https://github.com/zarr-developers/zarr-python/issues/2134))
-  * Fixed-length string dtypes ([issue #2347](https://github.com/zarr-developers/zarr-python/issues/2347))
-  * Datetime and timedelta dtypes ([issue #2616](https://github.com/zarr-developers/zarr-python/issues/2616))
-  * Object dtypes ([issue #2616](https://github.com/zarr-developers/zarr-python/issues/2616))
-  * Ragged arrays ([issue #2618](https://github.com/zarr-developers/zarr-python/issues/2618))
-  * Groups and Arrays do not implement `__enter__` and `__exit__` protocols ([issue #2619](https://github.com/zarr-developers/zarr-python/issues/2619))
-  * Default filters for object dtypes for Zarr format 2 arrays ([issue #2627](https://github.com/zarr-developers/zarr-python/issues/2627))
+- Object dtypes ([issue #2616](https://github.com/zarr-developers/zarr-python/issues/2616))
+- Ragged arrays ([issue #2618](https://github.com/zarr-developers/zarr-python/issues/2618))
+- Groups and Arrays do not implement `__enter__` and `__exit__` protocols ([issue #2619](https://github.com/zarr-developers/zarr-python/issues/2619))
+- Default filters for object dtypes for Zarr format 2 arrays ([issue #2627](https://github.com/zarr-developers/zarr-python/issues/2627))
diff --git a/examples/custom_dtype/custom_dtype.py b/examples/custom_dtype/custom_dtype.py
@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.11"
+# requires-python = ">=3.12"
 # dependencies = [
 #   "zarr @ git+https://github.com/zarr-developers/zarr-python.git@main",
 #   "ml_dtypes==0.5.1",

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -76,6 +76,8 @@ nav:
         - Creation sub-module: api/zarr/deprecated/creation.md
   - release-notes.md
   - contributing.md
+  - Design documents:
+    - design/chunk-grid.md
 watch:
   - src/zarr
   - docs
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Upgrade to spec0 compat (python 3.14 max, python 3.12 min).
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Optimize the performance of indexing operations when using an array-like indexer on a single dimension.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Remove the warning that is emitted when any Numcodecs codec is instantiated.