---
title: "PyIceberg"
description: "PyIceberg is the official Python implementation of Apache Iceberg — a pure-Python library for reading, writing, and managing Iceberg tables and catalogs without requiring Spark or a JVM."
canonical: "https://motherduck.com/glossary/pyiceberg/"
related:
  - title: "Apache Iceberg | MotherDuck Docs"
    url: "https://motherduck.com/docs/integrations/file-formats/apache-iceberg/"
  - title: "DuckLake Architecture Deep Dive"
    url: "https://motherduck.com/blog/ducklake-architecture-deep-dive/"
  - title: "DuckDB & Iceberg : The Future of Lightweight Data Management | MotherDuck"
    url: "https://motherduck.com/videos/duckdb-iceberg-the-future-of-lightweight-data-management/"
gated_asset:
  title: "DuckLake on MotherDuck"
  url: "https://motherduck.com/product/ducklake/"
---

# PyIceberg

> PyIceberg is the official Python implementation of Apache Iceberg — a pure-Python library for reading, writing, and managing Iceberg tables and catalogs without requiring Spark or a JVM.

## Overview
PyIceberg is a Python library, maintained under the Apache Iceberg project, that implements the Iceberg table format natively in Python. Before PyIceberg, working with Iceberg tables typically meant going through Spark, which pulls in a JVM dependency even for simple read or metadata operations. PyIceberg lets Python code load a table, inspect its schema and snapshots, plan a scan, and read the resulting data as a pandas DataFrame or PyArrow Table, all without a Spark cluster.

<glossary-callout guide="ducklake-lakehouse-table-format-book-full" />

## What it's used for
Common uses include lightweight table inspection and maintenance scripts, small-to-medium ETL jobs that don't need distributed compute, and building custom tooling or services on top of Iceberg tables. PyIceberg supports the major Iceberg catalogs — REST, AWS Glue, Hive Metastore, and SQL catalogs — and can also perform basic writes (appends, and increasingly more complex operations) directly from Python.

## Typical workflow
```python
from pyiceberg.catalog import load_catalog

catalog = load_catalog("my_catalog", **{
    "uri": "https://catalog.example.com",
    "type": "rest",
})

table = catalog.load_table("sales.orders")
df = table.scan(row_filter="order_date >= '2026-01-01'").to_pandas()
```

## Using PyIceberg alongside DuckDB
Because PyIceberg can materialize a table scan as a PyArrow Table, it's straightforward to hand that result to DuckDB for further SQL analysis in the same process:

```python
import duckdb

arrow_table = table.scan().to_arrow()
duckdb.sql("SELECT region, SUM(amount) FROM arrow_table GROUP BY ALL").show()
```

For simpler cases, DuckDB's own `iceberg` extension can query Iceberg tables directly with SQL — via `iceberg_scan()` on files, or by attaching a REST catalog — without going through PyIceberg at all, which is often the more direct path when the goal is SQL analytics rather than programmatic table management.