{"id":7369,"library":"lightkube","title":"Lightweight Kubernetes Client","description":"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.","status":"active","version":"0.19.1","language":"en","source_language":"en","source_url":"https://github.com/gtsystem/lightkube","tags":["kubernetes","client","async","cloud-native","k8s"],"install":[{"cmd":"pip install lightkube","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides 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.","package":"lightkube-models","optional":false},{"reason":"Underpins all HTTP requests. Specific versions of httpx can cause compatibility issues and breaking changes in lightkube.","package":"httpx","optional":false}],"imports":[{"symbol":"Client","correct":"from lightkube import Client"},{"symbol":"AsyncClient","correct":"from lightkube import AsyncClient"},{"symbol":"codecs","correct":"from lightkube import codecs"},{"note":"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.","wrong":"from lightkube.models.core_v1 import Pod","symbol":"Pod","correct":"from lightkube.resources.core_v1 import Pod"},{"symbol":"ObjectMeta","correct":"from lightkube.models.meta_v1 import ObjectMeta"}],"quickstart":{"code":"import asyncio\nfrom lightkube import AsyncClient, ALL_NS\nfrom lightkube.resources.core_v1 import Pod\n\nasync def list_all_pods():\n    client = AsyncClient() # Automatically loads kubeconfig or in-cluster config\n    try:\n        print(\"Listing all pods in all namespaces:\")\n        async for pod in client.list(Pod, namespace=ALL_NS):\n            print(f\"  Pod: {pod.metadata.name}, Namespace: {pod.metadata.namespace}, Status: {pod.status.phase}\")\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n    finally:\n        await client.close()\n\nif __name__ == \"__main__\":\n    asyncio.run(list_all_pods())\n","lang":"python","description":"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."},"warnings":[{"fix":"For direct `next()` calls, convert to an iterator: `my_iterator = iter(client.list(...)); next(my_iterator)`.","message":"The `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.","severity":"breaking","affected_versions":">=0.17.0"},{"fix":"Review model instantiations for `apiVersion` and `kind` fields. It may be safe to remove explicit settings if using `kubernetes-models>=1.33`.","message":"Since `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.","severity":"breaking","affected_versions":">=0.17.2"},{"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.","message":"Lightkube'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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Python environment is `3.9` or higher. Check `lightkube`'s `pyproject.toml` for the exact `requires_python` range.","message":"Official Python version support has evolved. `lightkube v0.16.0` dropped official support for Python 3.8 while adding support for Python 3.13.","severity":"breaking","affected_versions":">=0.16.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Lightkube could not find a valid Kubernetes configuration file (kubeconfig) in standard locations or was unable to load in-cluster configuration.","error":"lightkube.core.exceptions.ConfigError: Configuration file ~/.kube/config not found."},{"fix":"Before calling `next()`, explicitly convert the `ListIterable` to an iterator: `my_iterator = iter(client.list(...)); next(my_iterator)`.","cause":"Attempting to use `next()` directly on the result of `client.list()` after `lightkube v0.17.0`.","error":"TypeError: 'ListIterable' object is not an iterator"},{"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.","cause":"A generic HTTP error (e.g., 500, 404, 403) returned from the Kubernetes API server, wrapped by `lightkube.ApiError`.","error":"httpx.HTTPStatusError: Server error '500 Internal Server Error' for URL: ..."},{"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'`.","cause":"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.","error":"from lightkube.resources.apps_v1 import Deployment\nImportError: cannot import name 'Deployment' from 'lightkube.resources.apps_v1'"}]}