pylakekeeper — Lakekeeper Python Client
Please visit https://docs.lakekeeper.io for Documentation!
pylakekeeper is the official Python client for
Lakekeeper, an Apache-Licensed, secure,
fast and easy to use implementation of the
Apache Iceberg REST Catalog specification.
It covers the two things a plain Iceberg REST client cannot do for you: the
Generic Tables API — register Lance, Delta, Parquet, images or any other dataset
format as first-class catalog tables — and Storage Access Management, mapping
Lakekeeper's vended credentials straight into the keys that lance, boto3, fsspec
and deltalake already expect. If you have questions, feature requests or just want a
chat, we are hanging around in Discord!
Quickstart
pip install pylakekeeper
from pylakekeeper import Client, StaticToken
lk = Client(
base_url="http://localhost:8181",
warehouse="my-warehouse",
auth=StaticToken("my-token"),
)
# Register a Lance dataset as a generic table
lk.generic_tables.create("ai.models", "embeddings", format="lance")
# Load it back with short-lived, vended S3 credentials
resp = lk.generic_tables.load("ai.models", "embeddings", vended=True)
import lance
lance.write_dataset(data, resp.location, storage_options=resp.lance_storage_options)
# ...or open the same location as an fsspec filesystem
import fsspec
fs = fsspec.filesystem("s3", **resp.fsspec_kwargs)
print(fs.ls(resp.location))
Need a running catalog first? The Lakekeeper
Getting Started Guide brings one up with
docker compose in a couple of minutes.
Scope and Features
pylakekeeper is deliberately small: httpx + pydantic, nothing else. It is not a
general-purpose Iceberg REST client — for the standard Iceberg surface use
PyIceberg, which pairs with this happily
(pip install 'pylakekeeper[iceberg]').
- Generic Tables: Register non-Iceberg datasets (Lance, Delta, Parquet, images, HDF5)
as first-class catalog tables and get
create/load/list/dropwithout faking Iceberg metadata. - Vended Credentials:
LoadGenericTableResponseexposeslance_storage_optionsandfsspec_kwargs, so short-lived credentials flow into your reader with no manual key-mapping. - OpenID Provider Integration:
client_credentials,device_codeandauthorization_codeflows, all with automatic token refresh — or just aStaticToken. - Fully Typed: Ships
py.typed; the package is checked undermypy --strict. - Well-Tested: Unit tests plus an integration suite that runs a real round-trip
against Lakekeeper, Postgres, MinIO and Keycloak via
docker compose.
If you are missing something, we would love to hear about it in a GitHub Issue.
Status
Authentication Flows
| Flow | Status | Comment |
|---|---|---|
| Static Token | StaticToken — bring your own bearer token |
|
| OAuth2 Client Credentials | ClientCredentials, refreshes automatically |
|
| OAuth2 Device Code | DeviceCodeFlow — for CLIs and notebooks |
|
| OAuth2 Authorization Code | AuthorizationCodeFlow — local redirect server |
Generic Table Operations
| Operation | Status | Comment |
|---|---|---|
| Create | Any format identifier — see below | |
| Load | Optional credential vending via vended=True |
|
| List | Paginated | |
| Drop | ||
| Rename | Not yet exposed by the client |
GenericTableFormat provides constants for lance, delta, vortex, paimon and
dataset, but Lakekeeper stores the format as a free identifier — any string matching
^[a-z][a-z0-9_-]{0,63}$ is accepted, so pass a plain str for anything not listed.
Storage Backends
| Storage | Status | Comment |
|---|---|---|
| S3 - AWS | Vended credentials mapped to Lance / boto3 / fsspec | |
| S3 - Custom | MinIO, SeaweedFS and friends; allow_http set automatically |
|
| Azure ADLS Gen2 | No credential translation yet — raw vended properties are still available on the response | |
| Google Cloud Storage | No credential translation yet — raw vended properties are still available on the response |
Optional Extras
| Extra | Installs |
|---|---|
pip install 'pylakekeeper[lance]' |
pylance — write and read Lance datasets |
pip install 'pylakekeeper[iceberg]' |
pyiceberg — standard Iceberg catalog surface |
pip install 'pylakekeeper[examples]' |
Everything the notebooks and demo scripts need |
Examples
Runnable scripts and notebooks live in
python/examples/:
| Example | Description |
|---|---|
generic_tables_lance.py |
Create a Lance generic table, write and read a dataset with vended credentials |
dataset_images.py |
Upload image files to a dataset generic table via boto3 |
auth_clientcredentials_delta.ipynb |
OAuth2 client-credentials + a Delta Lake round-trip |
auth_devicecode_lance.ipynb |
Device-code login from a notebook |
auth_devicecode_hdf5.ipynb |
Store HDF5 files in a dataset table |
auth_authcode_vortex.ipynb |
Authorization-code flow with Vortex |
API Reference
| Object | Purpose |
|---|---|
Client |
Entry point; holds base URL, warehouse and auth |
client.generic_tables |
create / load / list / drop generic tables |
StaticToken, ClientCredentials, DeviceCodeFlow, AuthorizationCodeFlow |
Auth strategies |
LoadGenericTableResponse |
Location plus lance_storage_options / fsspec_kwargs |
iceberg_creds_to_lance, iceberg_creds_to_fsspec |
Credential mapping helpers |
All errors derive from LakekeeperError: NotFoundError, ConflictError, AuthError,
ConfigError, LakekeeperHTTPError.
Contributing
The client lives in the lakekeeper-clients monorepo alongside the Java and Spark clients.
git clone https://github.com/lakekeeper/lakekeeper-clients.git
cd lakekeeper-clients/python
pip install -e '.[dev]'
pytest tests/ # unit tests
pytest tests/integration -m integration # needs Docker
License
Licensed under the Apache License, Version 2.0
Metadata
Release files for pylakekeeper 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pylakekeeper-0.4.0.tar.gz | 338.7 kB | With provenance | Details for pylakekeeper-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pylakekeeper-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for pylakekeeper-0.4.0-py3-none-any.whl |
Total release size: 383.9 kB
Release files / pylakekeeper-0.4.0.tar.gz
| Download URL | pylakekeeper-0.4.0.tar.gz |
|---|---|
| Size | 338.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aa3343d9a29f10bf2c8574fb8103d2dcbee3f5875e39b084a0e8b4676588b6ce
|
|
BLAKE2b-256 checksum How to use checksums |
8e9aba901e2241fa3f6597f85baa9c630b8c2e4bb441fa7e8f77254fbf880942
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 21, 2026.
Transparency logRelease files / pylakekeeper-0.4.0-py3-none-any.whl
| Download URL | pylakekeeper-0.4.0-py3-none-any.whl |
|---|---|
| Size | 45.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f0941cdf4795fdf5bcf1b3b79f463400b1390f5a31368ea9b9ee83f6d178706a
|
|
BLAKE2b-256 checksum How to use checksums |
4fcd505c37e67846237e97124c1b689de4829dc1143e426646ec25e09172197a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 21, 2026.
Transparency logSecurity for pylakekeeper 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pylakekeeper-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.