lightkube

library0.21.0pypypi✓ verified 85d ago

Lightkube is a modern, lightweight Python client library for Kubernetes, providing a simple, type-hinted interface for interacting with the Kubernetes API. It supports both synchronous and asynchronous operations, facilitates loading resources from YAML, and automatically handles pagination. The current version is 0.19.1 and the library maintains an active release cadence with frequent updates to support new Kubernetes versions and add features.

devops

pip install lightkube

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LIGHTKUBE

lightkube

devopspythonv0.21.0

Install

2.8s avg

Import

1737ms

Disk

28MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.21.0 · 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

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 1.755s · 29.2MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.8s · import 1.720s · 30MB

28MB installed

● package 28MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ from lightkube import Client

AsyncClient

✓ from lightkube import AsyncClient

codecs

✓ from lightkube import codecs

Pod

✓ from lightkube.resources.core_v1 import Pod

✗ from lightkube.models.core_v1 import Pod

Import Kubernetes resources (e.g., Pod) from `lightkube.resources.*` for client methods, not directly from `lightkube.models.*`. Resources are subclasses of models with additional client-specific information.

ObjectMeta

✓ from lightkube.models.meta_v1 import ObjectMeta

This quickstart demonstrates how to initialize an `AsyncClient` and list all pods across all namespaces using asynchronous iteration. Lightkube automatically handles Kubernetes authentication via `kubeconfig` or in-cluster service accounts.

import asyncio from lightkube import AsyncClient, ALL_NS from lightkube.resources.core_v1 import Pod async def list_all_pods(): client = AsyncClient() # Automatically loads kubeconfig or in-cluster config try: print("Listing all pods in all namespaces:") async for pod in client.list(Pod, namespace=ALL_NS): print(f" Pod: {pod.metadata.name}, Namespace: {pod.metadata.namespace}, Status: {pod.status.phase}") except Exception as e: print(f"An error occurred: {e}") finally: await client.close() if __name__ == "__main__": asyncio.run(list_all_pods())

Debug

Known issues

breakingThe `client.list()` method changed its return type from an `Iterator` to an `Iterable` in `v0.17.0`. If you were directly using `next()` on the result, you must now explicitly call `iter()` first (e.g., `next(iter(client.list(...)))`). Iterating with a `for` loop remains unchanged.

fix

For direct `next()` calls, convert to an iterator: `my_iterator = iter(client.list(...)); next(my_iterator)`.

affects: >=0.17.0

breakingSince `kubernetes-models v1.33`, resource models will automatically have `apiVersion` and `kind` set upon initialization. Code that explicitly sets these fields on models might encounter unexpected behavior or redundancy.

fix

Review model instantiations for `apiVersion` and `kind` fields. It may be safe to remove explicit settings if using `kubernetes-models>=1.33`.

affects: >=0.17.2

gotchaLightkube's compatibility with `httpx` versions can be volatile. Specific `lightkube` versions might pin or limit `httpx` to avoid breaking changes in `httpx` itself. For instance, `v0.16.0` limited `httpx < 0.28.0` due to a breaking change in `httpx 0.28.0`.

fix

Consult `lightkube`'s `pyproject.toml` or `setup.cfg` for exact `httpx` version requirements if encountering `httpx`-related errors. Upgrade `lightkube` and ensure `httpx` is within the supported range.

affects: All versions

breakingOfficial Python version support has evolved. `lightkube v0.16.0` dropped official support for Python 3.8 while adding support for Python 3.13.

fix

Ensure your Python environment is `3.9` or higher. Check `lightkube`'s `pyproject.toml` for the exact `requires_python` range.

affects: >=0.16.0

gotchaThe `lightkube-models` package needs to be installed in a version compatible with your Kubernetes cluster's API version. Mismatched `lightkube-models` versions can lead to missing fields or incorrect API interactions.

fix

Install `lightkube-models` with a version range matching your Kubernetes API server, e.g., `pip install 'lightkube-models>=1.28,<1.29'` for Kubernetes 1.28.

affects: All versions

Errors

Common errors & fixes

lightkube.core.exceptions.ConfigError: Configuration file ~/.kube/config not found.

Lightkube could not find a valid Kubernetes configuration file (kubeconfig) in standard locations or was unable to load in-cluster configuration.

fix

Ensure a `~/.kube/config` file exists and is correctly configured, or that the application is running inside a Kubernetes cluster with a service account mounted.

TypeError: 'ListIterable' object is not an iterator

Attempting to use `next()` directly on the result of `client.list()` after `lightkube v0.17.0`.

fix

Before calling `next()`, explicitly convert the `ListIterable` to an iterator: `my_iterator = iter(client.list(...)); next(my_iterator)`.

httpx.HTTPStatusError: Server error '500 Internal Server Error' for URL: ...

A generic HTTP error (e.g., 500, 404, 403) returned from the Kubernetes API server, wrapped by `lightkube.ApiError`.

fix

Inspect the `e.status` attribute of the caught `lightkube.ApiError` for more details on the Kubernetes API error (e.g., `e.status.message`, `e.status.code`). Check API server logs for the specific issue.

from lightkube.resources.apps_v1 import Deployment ImportError: cannot import name 'Deployment' from 'lightkube.resources.apps_v1'

This usually indicates an incompatible `lightkube-models` version, where the requested resource definition is not present or has a different path in the installed models, or that `lightkube-models` isn't installed for the specific K8s version.

fix

Verify that `lightkube-models` is installed and its version range is compatible with the target Kubernetes cluster API version. For example, for K8s 1.28, you might need `pip install 'lightkube-models>=1.28,<1.29'`.

Upgrade

Version history

0.21.0latest on PyPI · released May 13, 2026

Audit

Dependencies

lightkube-modelsrequiredProvides Kubernetes API object definitions; users should install a version compatible with their Kubernetes cluster. E.g., `pip install 'lightkube-models>=1.28,<1.29'` for Kubernetes 1.28.

httpxrequiredUnderpins all HTTP requests. Specific versions of httpx can cause compatibility issues and breaking changes in lightkube.

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/gtsystem/lightkube ↗

packagehttps://pypi.org/project/lightkube/ ↗

homepagehttps://lightkube.readthedocs.io ↗