Skip to main content

Python client library for Kubernetes

Project description Code Coverage

IMPORTANT: This is a fork of kelproject/pykube which is no longer maintained (archived)!

Python client library for Kubernetes

Kel is an open source Platform as a Service (PaaS) from Eldarion, Inc. that makes it easy to manage web application deployment and hosting through the entire lifecycle from development through testing to production. It adds components and tools on top of Kubernetes that help developers manage their application infrastructure. Kel builds on Eldarion’s 7+ years experience running one of the leading Python and Django PaaSes.

For more information about Kel, see, follow us on Twitter @projectkel, and join our Slack team.


  • HTTP interface using requests using kubeconfig for authentication
  • Python native querying of Kubernetes API objects


To install pykube, use pip:

pip install pykube-ng


Query for all ready pods in a custom namespace:

import operator
import pykube

api = pykube.HTTPClient(pykube.KubeConfig.from_file("/Users/<username>/.kube/config"))
pods = pykube.Pod.objects(api).filter(namespace="gondor-system")
ready_pods = filter(operator.attrgetter("ready"), pods)

Access any attribute of the Kubernetes object:

pod = pykube.Pod.objects(api).filter(namespace="gondor-system").get(name="my-pod")

Selector query:

pods = pykube.Pod.objects(api).filter(
    selector={"": {"api-web", "api-worker"}},
pending_pods = pykube.objects.Pod.objects(api).filter(
    field_selector={"status.phase": "Pending"}

Watch query:

watch = pykube.Job.objects(api, namespace="gondor-system")
watch = watch.filter(field_selector={"": "my-job"}).watch()

# watch is a generator:
for watch_event in watch:
    print(watch_event.type) # 'ADDED', 'DELETED', 'MODIFIED'
    print(watch_event.object) # pykube.Job object

Create a Deployment:

obj = {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
        "name": "my-deploy",
        "namespace": "gondor-system"
    "spec": {
        "replicas": 3,
        "selector": {
            "matchLabels": {
                "app": "nginx"
        "template": {
            "metadata": {
                "labels": {
                    "app": "nginx"
            "spec": {
                "containers": [
                        "name": "nginx",
                        "image": "nginx",
                        "ports": [
                            {"containerPort": 80}
pykube.Deployment(api, obj).create()

Delete a Deployment:

obj = {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
        "name": "my-deploy",
        "namespace": "gondor-system"
pykube.Deployment(api, obj).delete()

Check server version:

api = pykube.HTTPClient(pykube.KubeConfig.from_file("~/.kube/config"))


pykube can be used together with HTTPie for Kubernetes command line querying goodness. For example:

pip install httpie
http pykube://minikube/api/v1/services

The above example will construct an HTTP request to the cluster behind the minikube context and show you the response containing all services.


  • Python 3.6+
  • requests (included in install_requires)
  • PyYAML (included in install_requires)

Local Development

You can run pykube against your current kubeconfig context, e.g. local Minikube:

$ pipenv install --dev
$ pipenv run python3
>>> import pykube
>>> config = pykube.KubeConfig.from_file('~/.kube/config')
>>> api = pykube.HTTPClient(config)
>>> list(pykube.Deployment.objects(api))

To run PEP8 (flake8) checks and unit tests including coverage report:

$ make test


The code in this project is licensed under the Apache License, version 2.0 (included in this repository under LICENSE).


Easiest way to contribute is to provide feedback! We would love to hear what you like and what you think is missing. Create an issue or ping try_except_ on Twitter.

PRs are welcome. Please also have a look at issues labeled with “help wanted”.

Code of Conduct

In order to foster a kind, inclusive, and harassment-free community, the Kel Project follows the Contributor Covenant Code of Conduct.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pykube-ng, version 0.17a2
Filename, size File type Python version Upload date Hashes
Filename, size pykube_ng-0.17a2-py2.py3-none-any.whl (26.4 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size pykube-ng-0.17a2.tar.gz (20.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page