Install & Compatibility
Where this runs
tested against v1.86.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.244s · 34.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.9s · import 2.084s · 34MB
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Configuration
✓ from lakefs_sdk import Configuration
Used to configure the API client with host and credentials.
ApiClient
✓ from lakefs_sdk import ApiClient
Initializes the API client using the configured settings.
RepositoriesApi
✓ from lakefs_sdk.apis import RepositoriesApi
Example for accessing repository-related API endpoints. Other API groups (e.g., `BranchesApi`, `ObjectsApi`) are accessed similarly.
ApiException
✓ from lakefs_sdk.rest import ApiException
Common exception class for API errors.
lakefs_client
✓ from lakefs_sdk import Configuration, ApiClient
✗ import lakefs_client
The `lakefs-client` package is deprecated and no longer supported for new updates or features. Migrate to `lakefs-sdk` for low-level access or `lakefs` for high-level operations.
This quickstart demonstrates how to configure the `lakefs-sdk` client using environment variables and then list all available repositories. Ensure `LAKEFS_SERVER_ENDPOINT_URL`, `LAKEFS_ACCESS_KEY_ID`, and `LAKEFS_SECRET_ACCESS_KEY` are set in your environment.
import os
import lakefs_sdk
from lakefs_sdk.apis import RepositoriesApi
from lakefs_sdk.rest import ApiException
# Configure API client with credentials from environment variables
configuration = lakefs_sdk.Configuration(
host=os.environ.get('LAKEFS_SERVER_ENDPOINT_URL', 'https://example.lakefs.io/api/v1'),
username=os.environ.get('LAKEFS_ACCESS_KEY_ID', ''),
password=os.environ.get('LAKEFS_SECRET_ACCESS_KEY', '')
)
# Create an API client instance
with lakefs_sdk.ApiClient(configuration) as api_client:
# Create an instance of the Repositories API
repositories_api = RepositoriesApi(api_client)
try:
# List repositories
repos = repositories_api.list_repositories()
print("Successfully connected to lakeFS!")
print("Repositories:")
for repo in repos.results:
print(f"- {repo.id}")
except ApiException as e:
print(f"Error connecting to lakeFS or listing repositories: {e}")
print("Ensure LAKEFS_SERVER_ENDPOINT_URL, LAKEFS_ACCESS_KEY_ID, and LAKEFS_SECRET_ACCESS_KEY are set.")
Debug
Known issues
breakingThe `lakefs-client` package is deprecated as of lakeFS 1.0 (last release v1.44.0) and is no longer supported for new updates or features. Users should migrate to `lakefs-sdk` (for low-level API access) or the higher-level `lakefs` package.fixReplace `lakefs-client` imports and usage with `lakefs_sdk` or `lakefs`. Refer to the 'Migrating to 1.0' guide for specific code changes.
affects: <=1.44.0 (lakefs-client)
gotchaThere are two main Python SDKs for lakeFS: `lakefs-sdk` (low-level, auto-generated, direct API calls) and `lakefs` (high-level, Pythonic interface for common operations like branches, commits, objects, transactions). Choosing the wrong SDK can lead to more complex code than necessary for common tasks.fixFor most common lakeFS operations, the `lakefs` (high-level) SDK is recommended for its simpler interface. Use `lakefs-sdk` when you need full control over API requests or features not exposed by the high-level SDK.
affects: All versions
breakingMigrating to lakeFS 1.0 and the `lakefs-sdk` from older `lakefs-client` versions involved API changes, such as renaming the `model` module to `models` and `apis` to `api`. Also, fetching results from response objects changed from dictionary-like access (`get_property`) to direct attribute access (`prop_name`).fixUpdate import paths (e.g., `lakefs_client.model` to `lakefs_sdk.models`, `lakefs_client.apis` to `lakefs_sdk.apis`) and adapt result parsing to use direct object attributes instead of `get_property`.
affects: Migrations from lakefs-client <1.0 to lakefs-sdk >=1.0
gotchaThe `lakefs-sdk` requires explicit configuration of host and credentials. Unlike the higher-level `lakefs` SDK, it does not automatically infer identity from environment variables (`LAKEFS_ACCESS_KEY_ID`, `LAKEFS_SECRET_ACCESS_KEY`, `LAKEFS_SERVER_ENDPOINT_URL`) or a local `.lakectl.yaml` file without explicit handling.fixAlways explicitly pass `host`, `username`, and `password` to `lakefs_sdk.Configuration`. Use `os.environ.get()` to read credentials from environment variables if desired.
affects: All versions
deprecatedOpenID Connect (OIDC) support for authentication via older configuration methods is deprecated. For single sign-on (SSO) or short-lived token (STS-like) authentication, users should consider lakeFS Cloud or Enterprise features.fixRefer to the latest lakeFS documentation on 'Short-Lived Tokens (STS)' and 'Authentication' for current recommended patterns for SSO and temporary credential usage.
affects: All versions where OIDC was previously configurable
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'lakefs_sdk'
The `lakefs-sdk` package is either not installed in the current Python environment or there's a typo in the import statement.
fixEnsure the package is installed using `pip install lakefs-sdk`. If you intended to use the high-level SDK, install and import `lakefs` instead (i.e., `pip install lakefs` and `import lakefs`).
lakefs_sdk.rest.ApiException: (401) Reason: Unauthorized
The API client is configured with incorrect or missing authentication credentials (username/password or access token) for the lakeFS server.
fixVerify that the `host`, `username`, and `password` (or `access_token`) provided in `lakefs_sdk.Configuration` match the credentials configured for your lakeFS instance.
urllib3.exceptions.MaxRetryError: HTTPConnectionPool(...) connect: Connection refused
The client application is unable to establish a network connection to the specified lakeFS server host and port, often due to an incorrect host address, firewall rules, or the lakeFS server not running.
fixCheck the `host` parameter in your `lakefs_sdk.Configuration` to ensure it's correct. Verify that the lakeFS server is running and accessible from the machine where your client code is executing, checking network connectivity and firewall settings.
UserWarning: Core Pydantic V1 functionality isn't compatible with Python 3.14 or greater. from pydantic.v1 import validate_arguments, ValidationError.
The `lakefs-sdk` uses Pydantic V1 compatibility features which are not fully compatible with Python 3.14 and later, leading to this warning from the underlying Pydantic library.
fixWhile the SDK might still function, consider using Python 3.13 or an earlier version to avoid potential compatibility issues with Pydantic V1 features. Monitor for future `lakefs-sdk` releases that explicitly support Pydantic V2 and Python 3.14+.
Upgrade
Version history
1.86.0latest on PyPI · released Aug 5, 2026
Audit
Dependencies
PythonrequiredRequired runtime environment