Install Kubernetes Python Client

The Kubernetes Python client lets you manage clusters directly from Python code. You can list pods, create deployments, and watch resources without calling kubectl.

This guide covers installation, authentication, first API calls, and troubleshooting. It is written for beginners who want a clean and working setup.

Prerequisites

You need Python 3.7 or newer and access to a Kubernetes cluster. A local cluster like minikube or kind works fine for learning.

Check your Python version with the command below.

python --version
python3 --version

Set Up a Virtual Environment

Always isolate project dependencies. A virtual environment prevents version conflicts between libraries.

# Create a virtual environment
python -m venv k8s-env

# Activate on Linux or macOS
source k8s-env/bin/activate

# Activate on Windows
k8s-env\Scripts\activate

Your prompt should change after activation. Confirm the correct Python path with which python or where python.

Install the Kubernetes Client with pip

The official package is called kubernetes. Install it with pip inside your active environment.

pip install --upgrade kubernetes

The --upgrade flag ensures you get the latest stable release. This matters because the client generates API bindings for each Kubernetes version.

Pin the Client Version

Version pinning keeps generated API behavior predictable. The client version 35.y.z maps to Kubernetes 1.35[reference:0].

Pin the version in your requirements.txt to avoid surprises in production.

pip install "kubernetes==35.0.0"

If you use a different tool, the same version pin applies.

uv add "kubernetes==35.0.0"
poetry add "kubernetes==35.0.0"

Keep the client version aligned with your cluster minor version when possible. Mismatches can cause missing fields or unexpected API errors[reference:1].

Install Optional Extras

The client supports optional authentication providers. Install an extra only if your cluster uses that provider.

# For Google Cloud authentication
pip install "kubernetes[google-auth]"

# For Azure Active Directory authentication
pip install "kubernetes[adal]"

If your kubeconfig relies on these providers, the extra avoids authentication failures later[reference:2].

If you also store cluster backups or logs in cloud storage, you can install google-cloud-storage in Python alongside this client.

Load Configuration

Before you create an API object, load the configuration. The client cannot authenticate without it[reference:3].

There are two common ways to authenticate. Choose the method that matches where your code runs.

Load a Local kubeconfig

Use this method on a development machine or in a CI job with a kubeconfig file. Call config.load_kube_config() to read the default file at ~/.kube/config[reference:4].

from kubernetes import client, config

# Load the default kubeconfig
config.load_kube_config()

# Create a CoreV1Api client
v1 = client.CoreV1Api()
print("Client configured successfully.")

Client configured successfully.

If your kubeconfig has multiple contexts, pass the context argument to target a specific cluster[reference:5].

config.load_kube_config(context="my-cluster-context")

You can also pass a custom file path when the kubeconfig is not in the default location[reference:6].

config.load_kube_config(config_file="/path/to/kubeconfig.yaml")

Load In-Cluster Credentials

Use this method only when your code runs inside a Kubernetes pod. The service account token and CA bundle must be mounted automatically.

Call config.load_incluster_config() to read the mounted credentials[reference:7].

from kubernetes import client, config

# Load credentials from the pod's service account
config.load_incluster_config()

# Create a CoreV1Api client
v1 = client.CoreV1Api()
print("In-cluster client ready.")

In-cluster client ready.

This method fails if the pod does not have a mounted service account. Always test it inside the cluster.

Make Your First API Call

Listing pods is a simple way to verify the setup. The example below lists pods in the default namespace[reference:8].

from kubernetes import client, config

config.load_kube_config()
v1 = client.CoreV1Api()

# List pods in the default namespace
pods = v1.list_namespaced_pod(namespace="default")

for pod in pods.items:
    print(pod.metadata.name, pod.status.phase)

nginx-deployment-6b474476c4-2xj9k Running
redis-cache-0 Running

If this output prints pod names, your client is working correctly.

For cluster-wide monitoring, use list_pod_for_all_namespaces() instead.

Troubleshoot Common Errors

Installation errors usually fall into three categories. Module conflicts, authentication problems, and version mismatches.

ModuleNotFoundError: No module named 'kubernetes'

This error means the package is not installed in your active environment. Activate your virtual environment and install the client again.

If you use conda, the package name is different. Install python-kubernetes instead of kubernetes[reference:9].

conda install python-kubernetes

Also check for conflicting packages like openshift. Uninstall and reinstall both with compatible versions if needed[reference:10].

401 Unauthorized

A 401 error means authentication failed. The kubeconfig may use an exec plugin that the Python client does not support[reference:11].

Test the plugin manually. If it returns a token, you can temporarily update the kubeconfig to use that token directly[reference:12].

Alternatively, switch to a kubeconfig that uses a static token or client certificate.

Version Mismatch Errors

If API calls fail with missing fields, the client and cluster versions may be misaligned. Pin the client to match your cluster minor version.

Check your cluster version with kubectl version. Then install the matching client version.

Best Practices for a Clean Setup

Pin the client version in your dependency file. Generated APIs change between versions, and reproducibility matters.

Load configuration once and reuse the API client. Creating a new client for every request wastes resources.

Never hardcode tokens or kubeconfig paths. Read them from environment variables or mounted secrets.

Monitor API failures in production. You can install sentry-sdk in Python and capture exceptions from your Kubernetes automation scripts.

If your automation filters cluster resources before processing, you can apply similar patterns to django-filter in Python for consistent query logic across services.

Use watches for real-time updates instead of polling. The client supports watch streams through the watch module.

Keep your kubeconfig small and scoped. Use separate contexts for staging and production to avoid accidental changes.

Conclusion

Installing the Kubernetes Python client is a short process. Create a virtual environment, install the kubernetes package, and load your configuration.

Use load_kube_config() for local development and load_incluster_config() for pods. Verify the setup with a simple pod listing.

Pin the client version to match your cluster. Handle authentication errors by checking kubeconfig plugins and credentials.

With these steps, your Python application can manage Kubernetes resources reliably and safely.