{"id":5280,"library":"kestra","title":"Kestra Python Client","description":"Kestra is an infinitely scalable orchestration and scheduling platform that allows users to create, run, schedule, and monitor complex pipelines. The Python client library facilitates programmatic interaction with the Kestra API for managing flows, executions, and sending metrics, outputs, and logs from within Python script tasks. The library is currently at version 1.3.0 and maintains a regular release cadence with frequent updates.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/kestra-io/libs","tags":["orchestration","workflow","etl","data pipeline","scheduler","automation"],"install":[{"cmd":"pip install kestra","lang":"bash","label":"Install Kestra Python Client"},{"cmd":"pip install python-dotenv # Optional, for managing environment variables","lang":"bash","label":"Install python-dotenv"}],"dependencies":[],"imports":[{"note":"Used for programmatic execution and management of Kestra flows.","symbol":"Flow","correct":"from kestra import Flow"},{"note":"Used within Python script tasks inside Kestra flows for sending outputs, metrics, and logs.","symbol":"Kestra","correct":"from kestra import Kestra"},{"note":"While 'kestra' is the PyPI package, the internal SDK modules are exposed under 'kestrapy'. For programmatic client configuration, use 'kestrapy'.","wrong":"from kestra import Configuration, KestraClient","symbol":"Configuration, KestraClient","correct":"from kestrapy import Configuration, KestraClient"}],"quickstart":{"code":"import os\nfrom kestrapy import Configuration, KestraClient\n\n# Configure client using environment variables or hardcoded values (not recommended for production)\nconfiguration = Configuration(\n    host=os.environ.get('KESTRA_HOST', 'http://localhost:8080'),\n    username=os.environ.get('KESTRA_USERNAME', 'root@root.com'), # or KESTRA_API_TOKEN\n    password=os.environ.get('KESTRA_PASSWORD', 'Root!1234')\n)\nkestra_client = KestraClient(configuration)\n\ntenant_id = os.environ.get('KESTRA_TENANT', 'main') # 'main' is default for OSS\nnamespace = \"my_namespace\"\nflow_id = \"my_flow\"\n\nflow_yaml = f'''\nid: {flow_id}\nnamespace: {namespace}\ntasks:\n  - id: hello\n    type: io.kestra.plugin.core.log.Log\n    message: \"Hello from a Kestra Python SDK created flow!\"\n'''\n\ntry:\n    # Create a flow\n    created_flow = kestra_client.flows.create_flow(tenant=tenant_id, body=flow_yaml)\n    print(f\"Flow created: {created_flow.id}\")\n\n    # Execute the flow\n    execution = kestra_client.executions.create_execution(tenant=tenant_id, flow_id=flow_id, namespace=namespace, wait=True)\n    print(f\"Execution finished with status: {execution.state.current}\")\n    \n    # Example of using Kestra within a flow (not directly runnable in quickstart, but demonstrates usage)\n    # from kestra import Kestra\n    # Kestra.outputs({\"message\": \"This is an output from within a flow!\"})\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to programmatically create and execute a Kestra flow using the Kestra Python SDK. It configures the client using environment variables for host, username, and password (or API token), then defines a simple flow in YAML and submits it to the Kestra instance. It then triggers an execution and waits for its completion. For in-flow interactions, the `kestra.Kestra` class is used within Python script tasks."},"warnings":[{"fix":"Ensure all API calls and client configurations specify a `tenant` ID. For Open Source, use `main`. Update any hardcoded API paths to include the tenant.","message":"Starting from Kestra 0.23.0 (and confirmed in 0.24.0 and 1.x), a tenant context is required. The `defaultTenant` (null tenant) is no longer supported. For Kestra Open Source, a fixed tenant named 'main' is always used, and all API URIs now include the tenant, e.g., `/api/v1/...` became `/api/v1/main/...`.","severity":"breaking","affected_versions":">=0.23.0"},{"fix":"Configure the `KestraClient` with either `username` and `password`, or an `access_token` (for service accounts). Avoid making unauthenticated API calls.","message":"With Kestra 0.24.0, basic authentication became required. Additionally, IAM and API endpoint changes were introduced.","severity":"breaking","affected_versions":">=0.24.0"},{"fix":"Run the provided migration scripts for your storage provider to update object paths. Failure to do so will prevent Kestra from accessing files with the old path structure.","message":"For users of S3 or GCS as internal storage, Kestra now removes the leading root slash in all storage paths to fix double slashes. This impacts how internal storage objects are accessed.","severity":"breaking","affected_versions":">=0.23.0"},{"fix":"For efficient dependency management, consider building a custom Docker image that includes Python and all required pip packages, or install packages at server startup if using the `Process Task Runner`. Alternatively, use caching for virtual environments in `WorkingDirectory` tasks.","message":"When running Python scripts within Kestra flows, managing dependencies can be tricky. Installing packages with `beforeCommands` downloads and installs them on every run, increasing execution time.","severity":"gotcha","affected_versions":"All"},{"fix":"Be mindful of the specific import paths based on whether you are writing an external Python script to interact with Kestra (use `kestrapy`) or writing a Python script to be executed within a Kestra flow (use `kestra`).","message":"The Python client package on PyPI is `kestra`, but the internal modules for programmatic client interaction (e.g., `Configuration`, `KestraClient`) are imported from `kestrapy`. For utilities used inside Kestra Python script tasks (e.g., `Kestra.outputs`), the import is `from kestra import Kestra`.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}