Crate icechunk 

A transactional storage engine for Zarr.

Icechunk provides version-controlled, transactional access to Zarr data on cloud object storage. It adds a layer of indirection between Zarr keys and on-disk storage, enabling:

• Serializable isolation - Reads are isolated from concurrent writes and always use a committed snapshot. Writes are committed atomically and never partially visible.
• Time travel - Previous snapshots remain accessible after new ones are written.
• Version control - Repositories support branches (mutable) and tags (immutable) that reference snapshots.

Core concepts

A repository contains a Zarr hierarchy (groups and arrays) with full version history. Each update creates a new snapshot with a unique ID. Branches are mutable references to snapshots (like Git branches), while tags are immutable references (like Git tags). The default branch is main.

Key types

• Repository - Handle to a versioned data store
• session::Session - Transaction context for reading/writing data
• Store - Zarr-compatible key-value interface backed by a Session

Architecture

Repository ─creates─► Session
                          ├── ChangeSet (uncommitted modifications)
                          └── AssetManager (typed I/O with caching)
                                  └── Storage (S3, GCS, Azure, local, etc.)

Re-exports

pub use config::ObjectStoreConfig;

pub use config::RepositoryConfig;

pub use repository::Repository;

pub use store::Store;

pub use icechunk_format as format;

Modules

asset_manager

Typed I/O layer for Icechunk assets.

change_set

Tracks uncommitted modifications during a session.

cli

Command-line interface for Icechunk operations.

compat

config

Configuration types for repositories and storage.

conflicts

Detection and resolution for concurrent writes.

diff

display

error

Generic error wrapper with span tracing.

feature_flags

inspect

Debugging utilities for examining repository state.

migrations

Upgrade repositories between Icechunk format versions.

ops

Repository maintenance operations.

refs

Branch and tag management.

repository

The entry point for Icechunk operations.

session

The transaction context for reading and writing data.

storage

Object store abstraction layer.

store

Zarr-compatible key-value interface.

virtual_chunks

References to external data sources.

Structs

ObjectStorage

Traits

Storage

Implementations are free to assume files are never overwritten.

Functions

new_in_memory_storage

new_local_filesystem_storage

new_s3_object_store_storage

new_s3_storage

user_agent

Returns the user-agent string for icechunk HTTP requests.

Type Aliases

StorageError