Install & Compatibility
Where this runs
tested against v36.0.2 · 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.925 runs
installs and imports cleanly · install 0.0s · import 1.718s · 59.1MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 5.7s · import 1.522s · 60MB
60MB installed
● package 60MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
client
✓ from kubernetes import client
Provides API client classes like CoreV1Api, AppsV1Api, etc. for interacting with Kubernetes resources.
config
✓ from kubernetes import config
Provides utilities for loading Kubernetes configuration (e.g., from kubeconfig file or in-cluster).
watch
✓ from kubernetes import watch
Provides Watch API for real-time monitoring of Kubernetes resources.
stream
✓ from kubernetes import stream
Used for handling streaming calls like pod exec or attach, especially for versions 4.0 and above.
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.")
Debug
Known issues
gotchaThe 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.fixFor 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.
affects: All versions of `kubernetes-client` (wrapper)
breakingThe 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).fixReview the compatibility matrix in the official documentation/GitHub README to ensure your client version matches your Kubernetes cluster version for full feature compatibility.
affects: Client versions v12 and below, transitioning to v17+
breakingMajor 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`).fixConsult 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.
affects: Versions affected by OpenAPI generator updates (e.g., around `v1943` issue on GitHub). Typically between major client versions (e.g., 20.x.x to 21.x.x, or 25.x.x to 26.x.x).
gotchaDirectly 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.fixUse 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.
affects: Client versions 4.0 and later
gotchaAlpha 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.fixAvoid 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.
affects: All versions
Errors
Common errors & fixes
urllib3.exceptions.MaxRetryError: HTTPSConnectionPool(host='****', port=6443): Max retries exceeded...
Client cannot establish a connection to the Kubernetes API server, often due to network issues, incorrect API server address, or firewall blocking access.
fixVerify 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.
ssl.CertificateError: hostname '****' doesn't match '****'
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.
fixEnsure 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`.
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"'...
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).
fixReview 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.
AttributeError: 'HTTPResponse' object has no attribute 'getheaders'
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.
fixUpgrade 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.
Upgrade
Version history
36.0.2latest on PyPI · released Jun 1, 2026
Audit
Dependencies
certifirequiredSSL certificate validation
durationpyrequiredDuration parsing utility
python-dateutilrequiredDate and time utilities
pyyamlrequiredYAML parsing for kubeconfig
requestsrequiredHTTP client library
requests-oauthlibrequiredOAuth 1.0/2.0 support for requests
sixrequiredPython 2/3 compatibility utilities
urllib3requiredHTTP client connection pooling
websocket-clientrequiredWebSocket protocol implementation
adaloptionalAzure Active Directory Authentication Library (optional for Azure Kubernetes Service integration)
google-authoptionalGoogle Authentication Library (optional for Google Kubernetes Engine integration)