Install & Compatibility
Where this runs
tested against v0.16.0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.720s · 36.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.3s · import 2.580s · 37MB
36MB installed
● package 36MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LakeFSClient
✓ from lakefs.client import LakeFSClient
Repository
✓ from lakefs.repository import Repository
Branch
✓ from lakefs.branch import Branch
Commit
✓ from lakefs.commit import Commit
This quickstart demonstrates how to initialize the lakeFS client and list existing repositories. The client automatically attempts to load configuration from environment variables (LAKECTL_SERVER_URL, LAKECTL_ACCESS_KEY_ID, LAKECTL_SECRET_ACCESS_KEY) or a `lakectl` configuration file. Ensure your lakeFS server is running and credentials are set up.
import os
from lakefs.client import LakeFSClient
# It's recommended to set these environment variables:
# LAKECTL_SERVER_URL (e.g., "http://localhost:8000")
# LAKECTL_ACCESS_KEY_ID
# LAKECTL_SECRET_ACCESS_KEY
# Initialize the client. It will attempt to load credentials
# from environment variables or a lakectl config file by default.
# You can also pass them explicitly:
# client = LakeFSClient(
# uri="http://localhost:8000",
# access_key_id="YOUR_ACCESS_KEY_ID",
# secret_access_key="YOUR_SECRET_ACCESS_KEY"
# )
try:
client = LakeFSClient(
uri=os.environ.get('LAKECTL_SERVER_URL', 'http://localhost:8000'),
access_key_id=os.environ.get('LAKECTL_ACCESS_KEY_ID', ''),
secret_access_key=os.environ.get('LAKECTL_SECRET_ACCESS_KEY', '')
)
# Example: List repositories
print("Attempting to connect to lakeFS and list repositories...")
repos_iterator = client.repositories.list()
repos = list(repos_iterator) # Consume the iterator
if repos:
print("Found repositories:")
for repo in repos:
print(f"- {repo.id}")
else:
print("No repositories found. Create one first (e.g., via lakectl CLI or UI).")
except Exception as e:
print(f"Error connecting to lakeFS or listing repositories: {e}")
print("Please ensure lakeFS server is running and credentials are configured correctly (environment variables or lakectl config file).")
lakectl --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'lakefs_client'
This error occurs because developers are attempting to import the deprecated `lakefs-client` package, which is an older, low-level SDK, instead of the current high-level `lakefs` SDK.
fixInstall the correct high-level SDK package using `pip install lakefs` and then import it as `import lakefs`.
lakefs.exceptions.NotAuthorizedException
The lakeFS Python SDK failed to authenticate with the lakeFS server, typically due to incorrect or missing access credentials (access key ID, secret access key) or an invalid host URL.
fixEnsure the `LAKEFS_ACCESS_KEY_ID`, `LAKEFS_SECRET_ACCESS_KEY`, and `LAKEFS_ENDPOINT_URL` environment variables are correctly set, or explicitly pass `username`, `password`, and `host` parameters when initializing `lakefs.client.Client`.
urllib3.exceptions.MaxRetryError: HTTPConnectionPool(...) Max retries exceeded with url: ... (Caused by ProtocolError('Connection aborted.', ConnectionResetError(...)))
The Python client was unable to establish or maintain a network connection with the lakeFS server, often indicating an incorrect server host/port, network issues (e.g., firewall blocking access), or the lakeFS server not being operational.
fixVerify that the `LAKEFS_ENDPOINT_URL` environment variable or the `host` parameter provided to `lakefs.client.Client` is accurate, and confirm that the lakeFS server is running and reachable from the environment where the Python code is executed.
lakefs.exceptions.NotFoundException: (404) Reason: Not Found HTTP response body: {"message":"repository not found"}
This error indicates that the repository, branch, or object you are trying to access with the SDK does not exist on the lakeFS server.
fixCheck for typos in repository, branch, or object names. Ensure that the resource has been created on the lakeFS server and that the client has the necessary permissions to access it.
UserWarning: Core Pydantic V1 functionality isn't compatible with Python 3.14 or greater.
This warning arises when the underlying `lakefs-sdk` (generated via OpenAPI Generator) uses Pydantic V1 compatibility layers that are not fully compatible with Python versions 3.14 and above, potentially leading to issues with data validation and API client functionality.
fixWhile this is often a warning rather than a hard error, it's best resolved by upgrading the `lakefs-sdk` to a version that officially supports Pydantic V2 and Python 3.14+, or by using a Python version earlier than 3.14 if an upgrade is not immediately available. Check the `lakefs-sdk` release notes for Pydantic V2 compatibility.
Upgrade
Version history
0.16.0latest on PyPI · released Apr 10, 2026
Audit
Dependencies
lakefs-clientrequiredThe lakeFS Python SDK (`lakefs`) is a high-level wrapper around the lower-level `lakefs-client` (the auto-generated API client). It is installed automatically as a dependency.