excelizarr

A cloud-native representation of an .xlsx workbook. In Zarr. Yes, really.

A friend made me realise you could save an .xlsx spreadsheet as an HDF5 file. That raised an obvious question: why not Zarr? Then a workbook is chunked, compressed and cloud-readable, and with Icechunk it's version-controlled too.

import excelizarr as xz

wb = xz.xlsx_to_zarr("model.xlsx", "s3://bucket/model.zarr")

wb["Inputs!B2:D10"]                                               # fetches a few chunks
df = xz.read_excel("s3://bucket/model.zarr", sheet_name="Inputs")  # == pd.read_excel
xz.zarr_to_xlsx("s3://bucket/model.zarr", "roundtrip.xlsx")       # formulas intact

How it works

Each sheet becomes a zarr group of aligned, chunked (and sharded) 2D arrays:

• kind: which type each cell holds
• one array per value type: number, string, bool, temporal
• formula and numfmt

Zarr never writes a chunk that's all fill value, so unused types and empty space cost nothing. A range read fetches only the chunks it overlaps, and the root's consolidated metadata means opening a workbook is a single read. See the format.

• read_excel parity. xz.read_excel runs pandas' own Excel parser over the stored cells, so every keyword behaves the same, and a hypothesis property checks the frames match.
• Round trips. Formulas, number formats, merged cells, column widths, frozen panes and defined names all survive xlsx → zarr → xlsx.
• Any zarr store. Local, s3://, in memory, a ZipStore, or an Icechunk session.
• In-place edits. wb["Inputs"]["B2"] = 42 rewrites the one shard that cell is in.

Is it fast?

On a 50,000 × 20 sheet (details):

So HDF is still the right call for "the whole sheet as a DataFrame, fast". excelizarr is 14× faster than parsing the .xlsx, smaller on disk than either, and much better at the cloud-shaped jobs: range reads, partial access and version control.

From S3 (ap-southeast-2, from Australia), on a 500,000 × 20 sheet (details):

The range read costs the same at 10,000 rows as at 500,000: it only ever fetches the chunks it needs.

Development

pixi run test             # hypothesis-heavy test suite
pixi run -e docs docs     # executed MyST docs, warnings are errors
pixi run -e bench bench   # the benchmark above

Licence

The Not Fit For Purpose Licence, which is the Apache License 2.0 with a preamble. This tool is not fit for purpose. I don't care what your purpose is, this isn't it.