PyIceberg is the official Python client for Apache Iceberg, an open table format designed for huge analytic datasets. It provides a pure Pythonic experience, enabling DML operations and queries on Iceberg tables without a JVM, and integrates seamlessly with popular Python data tools like Polars, Pandas, and DuckDB. Currently at version 0.11.1, the library maintains a regular release cadence with minor feature releases and necessary patch updates.
pip install pyicebergVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize a local SQL catalog, define an Iceberg schema, create a new table, append PyArrow data to it, and then read the data back. It uses local file system for both catalog metadata and data storage.
If you relied on `Table.name` to include the catalog identifier, you should adjust your code. Use `Table.identifier` if you need the fully qualified identifier, or reconstruct the full name using the catalog information.
Migrate to the unified AWS credentials configuration methods provided by PyIceberg, often leveraging standard AWS environment variables or credentials files, or using new configuration keys like `s3.access-key-id`.
Consult the official release notes and upgrade guides for PyIceberg 0.11.0 to identify and adapt code that used deprecated features.
Utilize PyIceberg for metadata management, lightweight analytics, and integrating Iceberg into Python pipelines, while offloading heavy data processing to appropriate distributed compute frameworks.
Understand that PyIceberg primarily interacts with Iceberg table *metadata* and existing data. For generating new data files, consider using external Iceberg-compatible writing tools or engines that integrate with PyIceberg for catalog operations.
Be aware of the performance implications for delete operations, particularly with the CoW strategy, which can involve rewriting significant portions of data. Monitor for updates on MoR delete enhancements if frequent row-level deletions are critical for your use case.
Install PyIceberg with the appropriate SQL extra based on your database backend. For example, use `pip install 'pyiceberg[sql-postgres]'` for PostgreSQL or `pip install 'pyiceberg[sql-sqlite]'` for SQLite.
Ensure that necessary build tools and libraries are installed on `alpine` Linux environments before attempting to install PyIceberg. This typically includes `gcc` and `libc-dev` (or the `build-base` meta-package). For example, run `apk add gcc libc-dev` or `apk add build-base`.
Install the necessary package using `pip install pyiceberg` or with required extras, e.g., `pip install 'pyiceberg[s3fs,pyarrow]'`. For AWS Glue, use `%additional_python_modules pyiceberg` within your notebook or job configuration.
Double-check the table name and namespace for typos. Ensure the catalog configuration (`type`, `uri`, credentials) is correct and has the necessary permissions. If using an in-memory SQLite catalog for testing, ensure it's configured for a shared cache: `jdbc:sqlite:file::memory:?cache=shared`. For AWS Glue/Lake Formation, verify correct namespace handling.
Pin your `pydantic` version to avoid the problematic releases. You can downgrade to a version prior to 2.12.0 (e.g., `pip install pydantic<2.12.0`) or upgrade to a version where the regression is resolved and PyIceberg has adapted (e.g., `pip install pydantic>=2.12.3`).
The primary fix involves repairing the source metadata files to include the 'operation' field. If the files are generated by another system (e.g., Snowflake), consult that system's documentation or support to ensure conformant metadata generation.