cozip 2026.5.13

Python bindings to libcozip, the reference writer for the Cloud-Optimized ZIP (cozip) format.

---

What is cozip?

A ZIP file you can open like a table — over the network, without downloading it.

cozip puts a Parquet manifest called __metadata__ at byte 0 — one row per entry with name, offset, size, plus any columns you add (split, label, class...). DuckDB, Arrow, and Polars query it directly. Range requests fetch only the bytes you actually need.

A 20 GB archive becomes a queryable table.

It's still a ZIP. unzip, zipfile.ZipFile, your OS's preview window — all unchanged.

Install

pip install cozip

Usage

Two functions: write and read.

Write

import cozip
import polars as pl

df = pl.DataFrame({
    "path":  ["local/tile_001.tif", "local/tile_002.tif", "local/tile_003.tif"],
    "name":  ["tile_001.tif", "tile_002.tif", "tile_003.tif"],
    "split": ["train", "val", "train"],
    "label": ["cloud", "water", "forest"],
})

cozip.write("dataset.zip", df)

Two reserved columns. path is where the file lives on disk — it's consumed at write time and dropped. name is how the entry is stored inside the archive and becomes part of __metadata__. Every other column rides along and becomes queryable on read.

Read

df = cozip.read("dataset.zip")

Local file or remote URL — same call. You get a DataFrame back with one row per entry, including offset and size resolved against the archive.

df = cozip.read("https://example.com/dataset.zip")

# query the manifest like any DataFrame
batch = df.filter(pl.col("split") == "train").sample(32)

# batch.select(["name", "offset", "size"]) is everything you need
# to range-request the payloads

Bindings

Language	Install
Python	pip install cozip
R	install.packages("cozip", repos = "https://asterisk-labs.r-universe.dev")
Julia	Pkg.add("Cozip")
JavaScript	npm install cozip
WASM	browser bundle, no Node required
DuckDB	INSTALL cozip FROM community; LOAD cozip;
C	vendored single-header cozip.h

All bindings call into the same C11 core. Byte-exact behavior across runtimes.

Specification

The on-disk format is defined in SPEC.md. Any conforming implementation reads any cozip ever written.

License

MIT

Developed with ❤️ by