Open Source · Python Library

IceFrame: a DataFrame-style Python library for Apache Iceberg

PyIceberg underneath, a friendlier surface on top, and local execution through Polars.

IceFrame is an open-source Python library for creating, reading, updating and maintaining Apache Iceberg tables. It keeps PyIceberg underneath and runs queries locally with PyArrow and Polars. The latest release on PyPI is 0.13.0, published on August 9, 2026 and tagged v0.13.0. The project labels itself alpha.

Install

pip install iceframe
pip install "iceframe[aws]"   # S3 support
pip install "iceframe[mcp]"   # the MCP server

IceFrame 0.13.0 needs Python 3.9 or later, PyIceberg 0.11 or 0.12, and Polars 1.0 or later.

What it is

PyIceberg is the official Python implementation of Iceberg and deliberately low level. IceFrame wraps it so common table work is one call:

  • A DataFrame API: read_table, to_arrow, to_pandas, lazy, head, describe, count_rows and scan_batches.
  • A query builder with pushdown for WHERE, SELECT and LIMIT, re-applying anything it cannot push so results stay correct.
  • Native upserts and transactions on PyIceberg's atomic APIs.
  • Maintenance: expire snapshots, remove orphan files (dry run by default), and compact with bin-pack, sort or approximate z-order.
  • Data quality constraints where nulls fail by default, usable as a gate on writes.
  • Metadata tables as Polars frames: snapshots, files, partitions, manifests, history and refs.
  • Catalogs: REST catalogs such as Dremio and Apache Polaris with credential vending, plus PyIceberg's sql, memory, glue, hive and dynamodb catalogs.
  • A read-only MCP server so an agent can query tables without holding warehouse credentials.

Status

Alpha. The README title and the PyPI classifier both say so. 0.13.0 is the version to be on: it fixes three defects that caused silent data loss or silently wrong results in earlier releases, and it made the test suite run offline against a local SQLite catalog.

Limits the README states plainly:

  • Merge-on-read delete writes are not supported. Deletes are copy-on-write; reading tables that already contain delete files works.
  • Joins read each joined table in full. Only the driving table gets pushdown.
  • Z-order is an approximation, a hierarchical sort rather than a bit-interleaved curve.

The next version is in development and not yet published. Install 0.13.0.

Changelog

From the project's CHANGELOG.md, with dates matching the PyPI uploads. v0.13.0 is the only git tag; the entries before it were reconstructed from PyPI and git history.

  • 0.13.0 August 9, 2026 Correctness. Filtered compaction no longer replaces the whole table with the filtered subset, a compound AND no longer drops an operand it cannot push down, null rows now fail data quality constraints, and writes invalidate the query cache. remove_orphan_files is a dry run by default. The test suite runs offline, and exceptions derive from IceFrameError.
  • 0.12.0 June 12, 2026 A bugfix release from an end-to-end code review. The create_table_from_* helpers stop writing every row twice, pool_size is deprecated and ignored, and __version__ comes from package metadata.
  • 0.11.0 and 0.11.1 February 18, 2026 Published to PyPI without their sources committed, so the change set cannot be reconstructed from the repository.
  • 0.10.0 December 11, 2025 A large expansion of compaction, parts of which were later removed as dead code in 0.12.0.
  • 0.1.0 to 0.9.0 December 3 to 11, 2025 The initial releases, plus a 0.8.1 backport patch on December 19, 2025.

Upgrading from 0.12 or earlier? Read the 0.13.0 behaviour changes first.

Work with Alex