Install & Compatibility
Where this runs
tested against v1.1.21 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✓ 5.6s
py 3.12
✕ build_error
✓ 4.8s
py 3.13
✕ build_error
✓ 4.8s
py 3.9
✕ build_error
✕ build_error
181MB installed
● package 181MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Repository
✓ from icechunk import Repository
✗ from icechunk.repository import Repository
While submodules exist (e.g., `icechunk.repository`), the main classes and storage factories are often exposed directly at the top level for convenience.
s3_storage
✓ from icechunk import s3_storage
✗ from icechunk.storage import s3_storage
Storage factory functions are typically available directly from the top-level `icechunk` package.
This quickstart demonstrates how to create a local Icechunk repository, interact with it using Zarr through a writable session, commit changes, and then make further modifications requiring a new session. It also shows how to review the repository's commit history.
import icechunk as ic
import zarr
import numpy as np
import tempfile
import os
# Create a temporary directory for the local repository
temp_dir = tempfile.TemporaryDirectory()
repo_path = os.path.join(temp_dir.name, "my_icechunk_repo")
try:
# 1. Create a new Icechunk repository on the local filesystem
storage = ic.local_filesystem_storage(repo_path)
repo = ic.Repository.create(storage)
print(f"Repository created at: {repo_path}")
# 2. Create a writable session on the 'main' branch
session = repo.writable_session("main")
# 3. Access the Zarr store from the session
store = session.store # A zarr store
# 4. Use Zarr to create a group and an array
root = zarr.group(store=store)
data = np.arange(1000).reshape(10, 10, 10)
zarr_array = root.create_array(
'my_data',
shape=data.shape,
dtype=data.dtype,
chunks=(5, 5, 5)
)
zarr_array[:] = data
# 5. Commit the changes
snapshot_id = session.commit("Initial data commit")
print(f"First commit successful with snapshot ID: {snapshot_id}")
# A new session is required for further writes after a commit
session_2 = repo.writable_session("main")
store_2 = session_2.store
zarr_array_2 = zarr.open_array(store_2, 'my_data', mode='r+')
zarr_array_2[:5, :5, :5] = 999 # Overwrite a subset
snapshot_id_2 = session_2.commit("Overwrite some values")
print(f"Second commit successful with snapshot ID: {snapshot_id_2}")
# 6. Explore version history
print("\nRepository history:")
for snapshot in repo.log("main"):
print(f" ID: {snapshot.id}, Message: {snapshot.commit_message}")
finally:
# Clean up the temporary directory
temp_dir.cleanup()
print(f"\nCleaned up temporary directory: {temp_dir.name}")
icechunk --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'icechunk'
The 'icechunk' library is not installed in the current Python environment.
fixInstall the library using pip: `pip install icechunk` or conda: `conda install -c conda-forge icechunk`.
IcechunkError: repository error: error contacting storage error listing objects in object store service error.
Icechunk is encountering issues connecting to or listing objects in the configured cloud object storage bucket, potentially due to incorrect credentials, bucket policy, network issues, or unsupported storage configurations (e.g., S3 Express One Zone).
fixVerify storage credentials, bucket permissions, network connectivity, and ensure the storage configuration is compatible with Icechunk. Check the `region`, `endpoint_url`, `allow_http`, `force_path_style`, `bucket`, and `prefix` parameters carefully.
ConflictError
This error is raised when multiple uncoordinated processes or threads attempt to commit changes to the same Icechunk branch concurrently, and the branch's tip has changed since the session started, preventing inconsistent updates.
fixImplement a conflict resolution strategy, such as retrying the transaction after rebasing the session, or using a `try-except` block to catch `ConflictError` and re-run the operations within a new session based on the latest branch state.
TypeError: IcechunkStore.set(): `value` must be a Buffer instance. Got an instance of <type> instead.
The `IcechunkStore.set()` method was called with a `value` argument that is not an instance of `icechunk.Buffer` (or a type that can be converted to it).
fixEnsure that the `value` passed to `IcechunkStore.set()` is an `icechunk.Buffer` instance. If you have raw bytes, you may need to explicitly convert them, for example: `icechunk.Buffer.from_bytes(your_bytes_data)`.
ValueError: Stored and computed checksum do not match.
This error typically occurs when attempting to access Icechunk data directly via Zarr-python without properly configuring Zarr to use Icechunk's storage transformer, leading to a mismatch in how data chunks are interpreted or checksummed.
fixEnsure that when opening an Icechunk repository with Zarr, the Zarr store is correctly wrapped by an `IcechunkStore` instance to handle Icechunk's specific storage logic. Avoid direct Zarr access to Icechunk-managed data unless specifically intended and configured.
Upgrade
Version history
2.1.2latest on PyPI · released Jul 29, 2026
Audit
Dependencies
zarrrequiredIcechunk works with the Zarr V3 Specification and requires Zarr Python 3 for interaction with underlying data.