Registry / data / icechunk

icechunk

JSON →
library2.1.2pypypi✓ verified 21d ago

Icechunk is an open-source (Apache 2.0), transactional storage engine for tensor / ND-array data, designed for use on cloud object storage. It augments the Zarr core data model with features that enhance performance, collaboration, and safety in a multi-user cloud-computing context. The library is currently at version 2.0.1 and follows a versioning scheme where major versions align with the on-disk format, allowing for breaking API changes even in minor releases.

pip install icechunk
INSTALL
IMPORT
SIG · ICECHUNK
I
icechunk
datapythonv2.1.2
Install
5.1s avg
Import
1497ms
Disk
181MB
Pass rate
3/ 10
Env Coverage3 / 10
glibc
3.93.13
musl
3.93.13
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
musl
glibc
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
Debug
Known issues
breakingIcechunk 2.0.0 and later requires Python 3.12 or higher. Support for Python 3.11 was dropped.
fix
Upgrade your Python environment to 3.12 or a newer compatible version.
affects: >=2.0.0
breakingThe on-disk storage format changed with Icechunk 2.0.0. Existing repositories created with Icechunk 1.x must be migrated using the `upgrade_icechunk_repository()` function. This is an administrative operation and must be executed in isolation (no other readers/writers).
fix
Use `ic.upgrade_icechunk_repository(repo, dry_run=False)` to migrate your 1.x repository to the 2.0 format. Ensure no other processes are accessing the repository during migration.
affects: >=2.0.0
breakingEnums like `ChunkType` had their variants renamed from `UPPER_CASE` to `snake_case` (e.g., `ChunkType.INLINE` became `ChunkType.inline`).
fix
Update your code to use the new `snake_case` enum variant names.
affects: >=2.0.0
gotchaAfter a `writable_session.commit()` is successfully executed, that session becomes read-only. To make further changes and commit them, you must create a new `writable_session`.
fix
Always obtain a new `repo.writable_session()` instance for each set of modifications you intend to commit.
affects: All versions
gotchaConcurrent creation of an Icechunk repository in the same location from multiple processes is not safe.
fix
Ensure that repository creation is a singular, isolated operation. Once created, repositories can be opened concurrently.
affects: All versions
gotchaIcechunk's version policy allows breaking API changes to occur in minor releases (e.g., `2.0.0` to `2.1.0`), not just major versions, to align library versions with the on-disk format.
fix
Always review the changelog or release notes thoroughly before upgrading to any new minor version of Icechunk to understand potential breaking changes.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'icechunk'
The 'icechunk' library is not installed in the current Python environment.
fix
Install 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).
fix
Verify 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.
fix
Implement 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).
fix
Ensure 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.
fix
Ensure 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.
Agent activity
30 hits · last 30 days
node
24
OpenAI (training)
1
Resources