{"id":2981,"library":"lakefs","title":"lakeFS Python SDK","description":"The lakeFS Python SDK provides a high-level, ergonomic interface for interacting with a lakeFS data lake. It simplifies operations like creating repositories, managing branches, committing data, and performing data versioning tasks. The current library version is 0.16.0, with releases occurring periodically to support new lakeFS server features and improve usability, typically decoupled from the rapid server release cycle.","status":"active","version":"0.16.0","language":"en","source_language":"en","source_url":"https://github.com/treeverse/lakeFS/tree/master/clients/python-wrapper","tags":["data lake","version control","git","object storage","data engineering","mlops"],"install":[{"cmd":"pip install lakefs","lang":"bash","label":"Install lakeFS SDK"}],"dependencies":[{"reason":"The 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.","package":"lakefs-client","optional":false}],"imports":[{"symbol":"LakeFSClient","correct":"from lakefs.client import LakeFSClient"},{"symbol":"Repository","correct":"from lakefs.repository import Repository"},{"symbol":"Branch","correct":"from lakefs.branch import Branch"},{"symbol":"Commit","correct":"from lakefs.commit import Commit"}],"quickstart":{"code":"import os\nfrom lakefs.client import LakeFSClient\n\n# It's recommended to set these environment variables:\n# LAKECTL_SERVER_URL (e.g., \"http://localhost:8000\")\n# LAKECTL_ACCESS_KEY_ID\n# LAKECTL_SECRET_ACCESS_KEY\n\n# Initialize the client. It will attempt to load credentials\n# from environment variables or a lakectl config file by default.\n# You can also pass them explicitly:\n# client = LakeFSClient(\n#     uri=\"http://localhost:8000\",\n#     access_key_id=\"YOUR_ACCESS_KEY_ID\",\n#     secret_access_key=\"YOUR_SECRET_ACCESS_KEY\"\n# )\n\ntry:\n    client = LakeFSClient(\n        uri=os.environ.get('LAKECTL_SERVER_URL', 'http://localhost:8000'),\n        access_key_id=os.environ.get('LAKECTL_ACCESS_KEY_ID', ''),\n        secret_access_key=os.environ.get('LAKECTL_SECRET_ACCESS_KEY', '')\n    )\n    \n    # Example: List repositories\n    print(\"Attempting to connect to lakeFS and list repositories...\")\n    repos_iterator = client.repositories.list()\n    \n    repos = list(repos_iterator) # Consume the iterator\n\n    if repos:\n        print(\"Found repositories:\")\n        for repo in repos:\n            print(f\"- {repo.id}\")\n    else:\n        print(\"No repositories found. Create one first (e.g., via lakectl CLI or UI).\")\n\nexcept Exception as e:\n    print(f\"Error connecting to lakeFS or listing repositories: {e}\")\n    print(\"Please ensure lakeFS server is running and credentials are configured correctly (environment variables or lakectl config file).\")","lang":"python","description":"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."},"warnings":[{"fix":"Refer to the official lakeFS Python SDK documentation on docs.lakefs.io for the latest compatibility matrix between SDK and server versions.","message":"The `lakefs` Python SDK (e.g., version 0.16.0) has its own versioning, which is independent of the lakeFS server version (e.g., 1.80.0). The SDK is generally backward compatible, designed to work with lakeFS server versions `v1.0.0` and later. However, always check the official documentation for specific compatibility notes, especially with major server upgrades or very old server instances.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always `import LakeFSClient from lakefs.client` and other high-level objects from `lakefs.*` modules. Avoid direct imports from `lakefs_client.*` unless you have a specific reason.","message":"The `lakefs` package is the high-level Python SDK, offering an ergonomic, object-oriented interface. The `lakefs-client` package is the lower-level, auto-generated API client. For most use cases, it is recommended to use the `lakefs` package directly, as `lakefs-client` is typically meant for internal SDK use or highly specific, advanced scenarios.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure environment variables are set, or provide `uri`, `access_key_id`, and `secret_access_key` explicitly when initializing `LakeFSClient`.","message":"Proper configuration of the `LakeFSClient` is crucial. The client attempts to load credentials and server URI from environment variables (e.g., `LAKECTL_SERVER_URL`, `LAKECTL_ACCESS_KEY_ID`, `LAKECTL_SECRET_ACCESS_KEY`) or a `lakectl` configuration file by default. Explicitly passing credentials as arguments overrides these defaults.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}