Install & Compatibility
Where this runs
tested against v2.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.910 runs
installs and imports cleanly · install 0.0s · import 0.416s · 22.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.9s · import 0.380s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Configuration
✓ from kfp_server_api import Configuration
✗ from kfp_server_api.swagger_client.configuration import Configuration
Top-level import for Configuration is preferred for v2 client.
ApiClient
✓ from kfp_server_api import ApiClient
PipelineServiceApi
✓ from kfp_server_api.api.pipeline_service_api import PipelineServiceApi
RunServiceApi
✓ from kfp_server_api.api.run_service_api import RunServiceApi
ExperimentServiceApi
✓ from kfp_server_api.api.experiment_service_api import ExperimentServiceApi
V2beta1Pipeline
✓ from kfp_server_api.models import V2beta1Pipeline
This quickstart demonstrates how to initialize the `kfp-server-api` client, configure its host, and make a basic call to list pipelines. It assumes KFP is running and accessible at the specified host. For production deployments, robust authentication (e.g., OAuth2, Bearer tokens from service accounts) would be required, which needs to be configured in the `Configuration` object.
import os
from kfp_server_api import Configuration, ApiClient
from kfp_server_api.api.pipeline_service_api import PipelineServiceApi
# Replace with your KFP API endpoint. E.g., 'http://localhost:8080/pipeline'
# or 'https://<your-kfp-host>/pipeline'
KFP_HOST = os.environ.get('KFP_SERVER_API_HOST', 'http://localhost:8080')
# Configure API key authorization: Bearer
# For most KFP deployments, you might need a service account token or session cookie.
# Example for no auth or basic local setup:
configuration = Configuration(host=KFP_HOST)
# For token-based auth (e.g., from a service account or user session):
# KFP_API_TOKEN = os.environ.get('KFP_SERVER_API_TOKEN')
# if KFP_API_TOKEN:
# configuration.access_token = KFP_API_TOKEN
# Create an API client
with ApiClient(configuration) as api_client:
# Create an instance of the PipelineServiceApi
pipeline_api = PipelineServiceApi(api_client)
try:
# List pipelines (requires appropriate authentication and permissions)
list_response = pipeline_api.list_pipelines()
print(f"Successfully connected to KFP API host: {KFP_HOST}")
print(f"Found {len(list_response.pipelines or [])} pipelines.")
for p in (list_response.pipelines or []):
print(f" - {p.display_name} (ID: {p.pipeline_id})")
except Exception as e:
print(f"Error connecting to KFP API or listing pipelines: {e}")
print("Make sure KFP_SERVER_API_HOST is correctly set and you have necessary authentication.")
Debug
Known issues
breakingThe `kfp-server-api` library is built for Kubeflow Pipelines v2. Code written for KFP v1 client libraries (e.g., `kubeflow-pipelines` or older `kfp` versions) will likely be incompatible due to significant changes in API contracts, models, and service endpoints.fixRewrite client code to use the KFP v2 API patterns and models. Refer to the KFP v2 SDK documentation for updated API specifications and client usage.
affects: All versions 2.x.x (compared to v1.x.x)
gotchaDirect usage of `kfp-server-api` requires explicit management of authentication and API endpoints. Unlike the higher-level `kfp` SDK, which often infers these from the environment or provides simpler `Client` objects, you must manually configure bearer tokens, cookies, or other authentication methods.fixSet `Configuration.host` to the KFP API endpoint and populate `Configuration.access_token` or other credential fields. For GCP, consider `google-auth` mechanisms. Ensure proper network access to the KFP backend.
affects: All versions
gotchaFor stability, it is crucial to ensure that the `kfp-server-api` version aligns with the version of the `kfp` SDK and the KFP backend server you are interacting with. Mismatched versions can lead to deserialization errors, unexpected API behavior, or missing features.fixAlways install `kfp-server-api` at the exact same version as your `kfp` SDK package (e.g., `pip install kfp-server-api==2.16.0 kfp==2.16.0`). Regularly update both together to match your KFP server deployment.
affects: All versions
Errors
Common errors & fixes
kfp_server_api.exceptions.ApiException: (401) Reason: Unauthorized
The Kubeflow Pipelines client lacks proper authentication credentials or the provided credentials (e.g., host, cookies, auth token) are invalid or expired, preventing access to the KFP API server.
fixEnsure the KFP client is initialized with correct authentication parameters. For out-of-cluster, explicitly set `host` and provide `auth_token` or `cookies`. For in-cluster, verify the service account and associated RBAC permissions.
AttributeError: module 'kfp_server_api' has no attribute 'ApiPipelineSpec'
This error occurs due to an incompatibility between the installed `kfp` SDK version and its `kfp-server-api` dependency, particularly during transitions or beta phases of KFP v2 where API object names changed.
fixUpgrade both the `kfp` SDK and `kfp-server-api` to compatible versions by running `pip install kfp --upgrade`. Always consult the official Kubeflow Pipelines documentation for recommended version pairings.
kfp_server_api.exceptions.ApiException: (404) Reason: Not Found
The Kubeflow Pipelines API server endpoint (host) configured in the client is incorrect, inaccessible, or the KFP backend itself is not running, misconfigured, or an incompatible version for the client.
fixVerify that the `host` parameter when initializing the `kfp.Client` points to the correct and accessible KFP API server URL (e.g., via `kubectl port-forward` or ingress). Ensure the KFP backend is running and that its version is compatible with your SDK (e.g., KFP SDK >= 2.0.0 requires KFP backend >= 2.0.0).
kfp_server_api.exceptions.ApiException: (500) - failed to authenticate with kubeflow pipeline
This error indicates a server-side issue or misconfiguration related to authentication, often following an attempt to connect or perform an action, even if initial client-side authentication steps were taken.
fixReview the Kubeflow Pipelines server logs for more specific authentication failures. Check the KFP deployment's authentication (e.g., Dex, Istio, IAP) and RBAC configurations to ensure the client's credentials are correctly processed by the backend.
Upgrade
Version history
2.17.0latest on PyPI · released Jul 9, 2026
Audit
Dependencies
No dependency data recorded yet.