Official Kubernetes Python Client

raw JSON →
35.0.0 verified Tue May 12 auth: no en install: verified quickstart: stale

The official Python client library for Kubernetes provides a comprehensive and low-level API to interact with Kubernetes clusters. It allows programmatic management of Kubernetes resources, automating tasks typically performed via `kubectl`. Maintained by the Kubernetes community, it mirrors the full Kubernetes API surface. The current stable version is 35.0.0, with releases following the Kubernetes versioning scheme for major versions.

pip install kubernetes

Common errors

error urllib3.exceptions.MaxRetryError: HTTPSConnectionPool(host='****', port=6443): Max retries exceeded... ↓
cause Client cannot establish a connection to the Kubernetes API server, often due to network issues, incorrect API server address, or firewall blocking access.
fix
Verify network connectivity from where the client is running to the Kubernetes API server (e.g., ping or telnet to the API server IP/port). Ensure correct KUBECONFIG is loaded, or load_incluster_config() is used within a cluster. Check firewall rules.
error ssl.CertificateError: hostname '****' doesn't match '****' ↓
cause Mismatch between the hostname in the SSL certificate presented by the API server and the hostname the client is trying to connect to. This can also be caused by outdated `ipaddress` or `urllib3` packages.
fix
Ensure your Kubernetes cluster's certificates are correctly configured for its hostname/IP. Alternatively, for development, you can disable SSL verification (client.Configuration.verify_ssl = False), but this is not recommended for production. Also, ensure ipaddress and urllib3 are up to date and meet the client's requirements.txt.
error kubernetes.client.rest.ApiException: (403) Reason: Forbidden HTTP response body: {'kind': 'Status', 'apiVersion': 'v1', 'metadata': {}, 'status': 'Failure', 'message': 'pods is forbidden: User "system:serviceaccount:default:default" cannot list resource "pods" in API group "" in the namespace "default"'... ↓
cause The service account or user credentials used by the client lack the necessary Role-Based Access Control (RBAC) permissions to perform the requested operation (e.g., list pods).
fix
Review and update Kubernetes RBAC policies. Create or modify ClusterRole and ClusterRoleBinding (or Role and RoleBinding) to grant the required permissions to the service account or user. Ensure kubeconfig context points to a user with sufficient privileges.
error AttributeError: 'HTTPResponse' object has no attribute 'getheaders' ↓
cause Incompatibility with `urllib3` versions. Specifically, `urllib3` versions 2.0.0+ deprecated `getheaders()` and 2.6.0+ removed it, while older `kubernetes` client versions might still use it.
fix
Upgrade your kubernetes client library to a version compatible with urllib3 2.0.0+. Alternatively, downgrade urllib3 to a version below 2.0.0 if you cannot update the Kubernetes client immediately, though upgrading the client is the recommended long-term solution.

Warnings

gotcha The PyPI package `kubernetes-client` (version 0.1.8 as originally specified in the prompt) is a sparsely documented wrapper project that states it's 'based on the official kubernetes-client'. Most users searching for 'Kubernetes Python client' are looking for the official `kubernetes` package. This entry describes the official `kubernetes` package, not the `kubernetes-client` wrapper. ↓
fix For comprehensive, official documentation and active development, use `pip install kubernetes` (the package described here). If `kubernetes-client` 0.1.8 was intentionally sought, be aware of its limited documentation and potential maintenance status.
breaking The versioning scheme for the official client changed starting with Kubernetes v1.17. Previously, client releases followed a different schema. Newer client versions (v17.x.x and above) align more closely with the Kubernetes minor and patch release numbers (vY.Z.P for Kubernetes v1.Y.Z). ↓
fix Review the compatibility matrix in the official documentation/GitHub README to ensure your client version matches your Kubernetes cluster version for full feature compatibility.
breaking Major breaking changes occurred related to the structure of API classes and property/parameter naming conventions in some releases (e.g., around OpenAPI generator updates). API classes might have moved, requiring import path updates (e.g., to `kubernetes.client.apis.tags.some_api`). ↓
fix Consult the `CHANGELOG.md` on the official GitHub repository for detailed migration steps when upgrading major client versions. Update import paths for API classes and adjust object property access based on new naming conventions.
gotcha Directly calling `exec` or `attach` methods (e.g., `api.connect_get_namespaced_pod_exec`) is no longer supported for streaming operations from client version 4.0 onwards. These calls will fail or behave unexpectedly. ↓
fix Use the `stream` module for `exec`, `attach`, and similar streaming calls. For example, instead of `resp = api.connect_get_namespaced_pod_exec(name, ...)`, use `resp = stream(api.connect_get_namespaced_pod_exec, name, ...)`. Refer to the `examples/exec.py` in the official repository.
gotcha Alpha APIs are unstable and can change significantly or disappear without prior notice in any release. Relying on them in production code carries a high risk of breaking changes. ↓
fix Avoid using Alpha APIs in production environments. If absolutely necessary, pin your client version and thoroughly test upgrades. Monitor Kubernetes release notes for Alpha API stabilization or removal.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) - - 1.52s 59.1M
3.10 alpine (musl) - - 1.48s 59.1M
3.10 slim (glibc) - - 1.06s 60M
3.10 slim (glibc) - - 1.04s 60M
3.11 alpine (musl) - - 2.30s 65.4M
3.11 alpine (musl) - - 2.18s 65.4M
3.11 slim (glibc) - - 1.77s 67M
3.11 slim (glibc) - - 1.82s 67M
3.12 alpine (musl) - - 1.79s 56.6M
3.12 alpine (musl) - - 1.76s 56.6M
3.12 slim (glibc) - - 1.72s 58M
3.12 slim (glibc) - - 1.73s 58M
3.13 alpine (musl) - - 1.69s 55.6M
3.13 alpine (musl) - - 1.65s 55.7M
3.13 slim (glibc) - - 1.79s 57M
3.13 slim (glibc) - - 1.62s 57M
3.9 alpine (musl) - - 1.42s 58.8M
3.9 alpine (musl) - - 1.47s 58.7M
3.9 slim (glibc) - - 1.21s 60M
3.9 slim (glibc) - - 1.29s 60M

Imports

Quickstart stale last tested: 2026-04-23

This quickstart demonstrates how to initialize the Kubernetes Python client by loading configuration (either in-cluster or from a kubeconfig file) and then listing all pods across all namespaces. It includes basic error handling for configuration loading and API calls, and is designed to be runnable in both cluster environments and local development setups with `KUBECONFIG` set.

import os
from kubernetes import client, config

# Load Kubernetes configuration
# Try to load in-cluster config first, then kubeconfig file
try:
    config.load_incluster_config()
    print("Loaded in-cluster Kubernetes config.")
except config.ConfigException:
    try:
        # Specify kubeconfig file path, defaults to ~/.kube/config
        kubeconfig_path = os.environ.get('KUBECONFIG', os.path.expanduser('~/.kube/config'))
        config.load_kube_config(config_file=kubeconfig_path)
        print(f"Loaded kubeconfig from {kubeconfig_path}.")
    except config.ConfigException:
        print("Could not load Kubernetes config from in-cluster or kubeconfig file.")
        print("Ensure you are running inside a cluster or have a valid KUBECONFIG set.")
        exit(1)

v1 = client.CoreV1Api()
print("Listing pods with their IPs:")
# Use watch=False for a single list operation
try:
    ret = v1.list_pod_for_all_namespaces(watch=False)
    for i in ret.items:
        print(f"{i.status.pod_ip}\t{i.metadata.namespace}\t{i.metadata.name}")
except client.ApiException as e:
    print(f"Error listing pods: {e}")
    print("Ensure your credentials have permissions to list pods.")
last verified Tue May 12
next check Wed Jul 15