zarr-python

用途

Zarr-Python 用于存储大型 N 维数组，具备分块（chunking）与压缩能力，适合高效并行 I/O、云原生工作流，以及与 NumPy、Dask、Xarray 的无缝集成。本条目是 Kalaris Labs 维护的社区指南，并非 zarr-developers 官方包。

当前上游版本为 zarr 3.2.1（2026-05-05 发布），文档见 zarr.readthedocs.io。新数组默认使用 Zarr 格式 3，如需旧格式互操作可设置 zarr_format=2。Zarr 3.2 新增 rectilinear chunks，并持续完善 v3 codec 流水线。

安装

uv pip install "zarr==3.2.1"

当前稳定版 Zarr-Python 需要 Python 3.12+ 与 NumPy 2.0+。对于远程存储（S3、GCS、HTTP），需在项目锁文件中固定可选 extras/后端：

uv pip install "zarr[remote]==3.2.1" "s3fs==2026.4.0" "gcsfs==2026.5.0"

仅当项目已有提交的锁文件与兼容性测试时，才使用 zarr>=3,<4 这类版本范围。对于 Zarr-Python 2 / Python 3.10–3.11 工作流，请从 support-v2 发布说明中选择精确的 zarr==2.x.y 补丁版本，并提交生成的锁文件。

主要能力

数组创建

import zarr
import numpy as np

z = zarr.create_array(
    store="data/my_array.zarr",
    shape=(10000, 10000),
    chunks=(1000, 1000),
    dtype="f4"
)
z[:, :] = np.random.random((10000, 10000))
data = z[0:100, 0:100]

提供多种便捷函数：zarr.zeros、zarr.ones、zarr.full、zarr.array、zarr.zeros_like。

打开已有数组

z = zarr.open_array('data.zarr', mode='r+')
z = zarr.open_array('data.zarr', mode='r')
z = zarr.open('data.zarr')  # 自动识别数组或组

读写数据

支持 NumPy 风格索引，包括切片、vindex 坐标索引、oindex 正交索引、blocks 块索引。

调整大小与追加

z.resize((15000, 15000))
z.append(np.random.random((1000, 10000)), axis=0)

组与层级

组可像目录或 HDF5 组一样组织多个数组：

root = zarr.group(store='data/hierarchy.zarr')
temperature = root.create_group('temperature')
temp_array = temperature.create_array(name='t2m', shape=(365, 720, 1440), chunks=(1, 720, 1440), dtype='f4')
array = root['temperature/t2m']
print(root.tree())

v3 组 API 使用 create_array / require_array（v3 已移除 h5py 风格的 create_dataset / require_dataset）。

属性与元数据

数组与组均可附加自定义属性，以 JSON 形式存储，必须可 JSON 序列化（字符串、数字、列表、字典、布尔、null）。

使用方式与参考文档

references/chunking_and_compression.md：按访问模式设定分块大小（目标约 1 MB，云端 5-100 MB）、sharding 与 codec 选择。
references/storage_backends.md：本地、内存、ZIP 及 fsspec 远程存储（S3、GCS），含凭据指引——优先使用 IAM 角色或工作负载身份，切勿打印凭据值。
references/integration.md：NumPy、Dask、Xarray 集成、线程安全与合并元数据。
references/performance_and_patterns.md：优化、可追加时间序列与大型矩阵模式、格式转换与故障排查。
references/api_reference.md 与 references/v3_migration.md：完整 API 与 v2 到 v3 迁移说明。

官方资源：文档 https://zarr.readthedocs.io/en/stable/ ；3.0 迁移指南 https://zarr.readthedocs.io/en/stable/user-guide/v3_migration/ ；存储后端 https://zarr.readthedocs.io/en/stable/user-guide/storage/ ；Zarr 规范 https://zarr-specs.readthedocs.io/ ；GitHub https://github.com/zarr-developers/zarr-python 。相关库：Xarray、Dask、NumCodecs。

适用场景

大型 N 维数组存储、并行 I/O、云原生工作流、与 NumPy/Dask/Xarray 配合的数据处理。

限制与注意事项

本指南为社区维护，非官方包。
版本相关细节可能过时，需对照已安装版本的官方文档确认。
不得编造结果、参数、标识符、引用或统计；未在本会话中计算的指标不得报告。
涉及费用、共享 GPU/云配额、个人或患者数据、不可撤销操作时，须先征得同意。
若指令中的函数、标志或端点在当前安装版本中缺失，应查阅该版本文档并告知用户，切勿臆造 API。
若必需输入、标识符或参数不明确，应询问用户或明确说明假设后再运行。