# kubernetes-client/python: the official Kubernetes client for Python, and how to pick the right version

> The kubernetes package on PyPI is the official Python client for the Kubernetes API. It is generated from the API spec, versioned against cluster releases, and the part most teams get wrong is the compatibility matrix, not the code.

**kubernetes-client/python** — Official Python client library for kubernetes

- Repository: https://github.com/kubernetes-client/python
- Website: http://kubernetes.io/
- Stars: 7,670 · Forks: 3,525
- Language: Python
- License: Apache-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/kubernetes-client-python

## What kubernetes-client/python actually is, and who ends up depending on it

This is the official Python client library for the Kubernetes API, published on PyPI under the package name kubernetes. It is not a wrapper around kubectl and it is not a YAML templating tool. It is a generated client: the API surface is produced from the Kubernetes API definition, which is why the repository carries a kubernetes/ directory with its own generated README covering every API and model, and why the version number tracks cluster releases rather than the library's own feature history.

The audience is narrow and specific. You are writing Python that needs to create, read, patch or watch Kubernetes objects as part of a larger program: a controller, a CI step that inspects cluster state, an operator's reconciliation loop, a script that annotates deployments across many clusters. If your task is one kubectl invocation, this library is more machinery than the job needs. If your task is a program whose control flow depends on what the cluster returns, this is the supported path.

The repository also ships an asyncio variant, exposed as kubernetes.aio, alongside the synchronous client. The README shows both, and the badge on the project page marks client support level as beta and client capabilities as Silver. That is a fair description of what you are getting: broad API coverage, with the async surface newer and less settled than the synchronous one.

## How the generated client maps Python calls onto the Kubernetes API

The data flow is direct. You build a client, usually by loading a kubeconfig, then call a method named after the API operation you want. The README's first example loads config with config.load_kube_config(), instantiates client.CoreV1Api(), and calls list_pod_for_all_namespaces(watch=False). The return value is an object whose .items attribute is a list of pod objects, each carrying .status.pod_ip, .metadata.namespace and .metadata.name. Those attribute names mirror the Kubernetes API object structure, because the models are generated from it.

Watching is a separate concern from listing. The watch module wraps a list call into a stream of events, and the README example passes _request_timeout=60 to the underlying list_namespace call while iterating over w.stream(...). Each event is a dict with a 'type' and an 'object', so the loop reads event['object'].metadata.name. The watch object also has a stop() method, which the example uses to break the loop after ten events.

Because models are generated, the cost of this design shows up in two places. Method names are long and mechanical, since they encode verb, scope and resource. And the object graph is deep: reaching a pod's IP means going through .status, not a convenience accessor. The trade-off buys you coverage of the API that stays current with upstream releases, which hand-written wrappers rarely manage.

## Installing kubernetes and listing pods from a kubeconfig

The README gives two installation routes. The simple one is from PyPI. The other builds from a source checkout, and it uses --recursive, which matters because the repository depends on submodules that a plain clone will not fetch.

```bash
pip install kubernetes
```

For a source install, the README's commands are:

```bash
git clone --recursive https://github.com/kubernetes-client/python.git
cd python
python -m pip install --upgrade .
```

Once installed, the smallest real program loads your kubeconfig and lists pods across all namespaces. The README's example does exactly this, and the output is one line per pod with its IP, namespace and name.

```python
from kubernetes import client, config

config.load_kube_config()

v1 = client.CoreV1Api()
ret = v1.list_pod_for_all_namespaces(watch=False)
for i in ret.items:
    print("%s\t%s\t%s" % (i.status.pod_ip, i.metadata.namespace, i.metadata.name))
```

If you are running inside a pod rather than on a workstation, the repository has examples/in_cluster_config.py for that case, and examples/out_of_cluster_config.py for the kubeconfig case. The examples folder is the intended learning path: the README says to run them with python -m examples.example1, substituting the filename you want. There are examples for deployment CRUD, cronjobs, jobs, ingresses, node labels, custom objects and patching a ConfigMap, so the fastest way to see the calling convention for a resource is to read the matching file rather than guess at method names.

## The compatibility matrix is the part that bites

The README states that client-python follows semver, so until the major version increases, your code continues to work with explicitly supported Kubernetes cluster versions. The word doing the work there is explicitly. The compatibility matrix lists, for each client major, one cluster version marked with a checkmark and other versions marked with (+-), meaning partial or approximate support.

Read a row and the shape is consistent. Client 35.y.z supports Kubernetes 1.35 with a checkmark, and 1.34 or below plus 1.36 or above with (+-). Client 34.y.z marks 1.34, client 33.y.z marks 1.33, and so on back through the list. The client major and the cluster minor are meant to line up. A cluster newer than your client's marked version is not a supported combination, it is a tolerated one, and the tolerance is what breaks at runtime when an API field or a resource version changes shape.

The practical consequence: pinning the client is not enough, you have to pin it against the cluster you actually run. A team on Kubernetes 1.35 that installs client 33.y.z is outside the checkmarked row, and the failure will not announce itself as a version mismatch. It will surface as a model that rejects an unknown field, or a call that returns a shape your code does not expect. The matrix is the document to check before a cluster upgrade, and the README does not offer a runtime guard that checks it for you.

## Where the client is the wrong tool, and what to use instead

Two limitations are worth stating plainly. First, the asyncio client is exposed as kubernetes.aio and the project's own badge marks client support level as beta. If you are building an async service and the async client's stability is a hard requirement, that badge is a signal to weigh, not a detail to skip. The synchronous client is the more established surface.

Second, this library is generated code, and generated code is a poor fit for tasks that are fundamentally about declaring desired state. If your job is to apply a directory of manifests and let the cluster converge, the client is the wrong layer: you would be reimplementing apply logic in Python. The repository does include examples/apply_from_directory.py and examples/apply_from_dict.py, which shows the client can do it, but doing it in Python when a declarative tool already does it is work you do not need.

A real alternative for the declarative case is the official Kubernetes tooling itself: kubectl apply for manifests and Helm for templated releases. The difference in approach is not cosmetic. kubectl and Helm send desired state and let the API server compute the diff, while this client sends explicit operations and returns objects you inspect in code. The client wins when the decision of what to send depends on program logic, such as reading one resource to decide how to patch another. It loses when the desired state is already written down in a file.

For the async case, the alternative is to run the synchronous client in a thread pool rather than adopt the beta async surface. That is a real option, and the trade-off is thread overhead against a less settled API.

## Maintenance, release cadence and what the Apache-2.0 licence means here

The repository is not archived, and the last push was on 2026-09-21, one day before this writing, so the project is being worked on. Recent releases show the cadence: v37.0.0a1 on 2026-09-02 as an alpha, v36.0.3 on 2026-07-13 and v36.0.2 on 2026-06-01 as stable releases. The alpha line and the stable line move separately, which is why the version you install from PyPI by default is a stable one unless you ask for the alpha.

Upgrade cost is dominated by the version coupling described above. Every cluster minor upgrade is a candidate client major upgrade, and the matrix is the only place that tells you which pair is supported. Budget for reading the matrix at each cluster upgrade rather than treating the client as a set-and-forget dependency.

The licence is Apache-2.0, stated in the repository's LICENSE file and in setup.py as license_expression. The dependency list in requirements.txt is not uniformly permissive: it annotates certifi as MPL, python-dateutil as BSD, pydantic as MIT, PyYAML as MIT, websocket-client as LGPLv2+, requests as Apache-2.0, requests-oauthlib as ISC, urllib3 as MIT, durationpy as MIT, and setuptools as PSF/ZPL. The LGPLv2+ entry is the one that most often triggers a review in organisations that restrict copyleft dependencies. That is a factual note about what the file says, not legal advice; if your policy screens licences, screen websocket-client.

## Frequently asked questions about choosing and running the client

The questions below are the ones that come up when a team is deciding whether to add kubernetes-client/python to a Python service, and each answer stays within what the repository and its README state.

## Conclusion

Adopt kubernetes-client/python when you are writing Python that talks to the Kubernetes API and you want the API surface generated from the upstream spec rather than hand-written. Do not adopt it for kubectl-style scripting, for Helm-style templating, or for an async service where the asyncio client's beta status is unacceptable. Before committing, check the compatibility matrix row for your cluster version and confirm the client major you pinned is the one whose row marks that version with a checkmark rather than with the (+-) tolerance.

## FAQ

### Which version of kubernetes-client/python should I install for my cluster?

Use the compatibility matrix in the README. Each client major marks one Kubernetes version with a checkmark and lists other versions with (+-), so the client major whose checkmark matches your cluster version is the supported pair.

### Does kubernetes-client/python support asyncio?

Yes, through the kubernetes.aio module, and the README shows an asyncio example that loads config with await config.load_kube_config() and uses ApiClient as an async context manager. The project's badge marks client support level as beta.

### How do I install kubernetes-client/python from source?

The README gives git clone --recursive https://github.com/kubernetes-client/python.git, then cd python, then python -m pip install --upgrade . The --recursive flag is part of the documented command.

### How do I watch Kubernetes resources instead of listing them once?

Use the watch module. The README example creates watch.Watch() and iterates over w.stream(v1.list_namespace, _request_timeout=60), where each event is a dict with a 'type' and an 'object', and w.stop() ends the stream.

### What licence does kubernetes-client/python use?

The repository is Apache-2.0. Its dependency list in requirements.txt includes websocket-client under LGPLv2+, which is worth noting if your organisation screens copyleft dependencies.

## Sources

- [kubernetes-client/python on GitHub](https://github.com/kubernetes-client/python)
- [License: Apache-2.0](https://github.com/kubernetes-client/python/blob/master/LICENSE)
- [Project website](http://kubernetes.io/)
- [README](https://github.com/kubernetes-client/python/blob/master/README.md)
- [Releases](https://github.com/kubernetes-client/python/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kubernetes-client-python