Kubernetes Asynchronous Python Client

raw JSON →
35.0.1 verified Tue May 12 auth: no python install: verified

kubernetes-asyncio is an asynchronous (AsyncIO) client library for interacting with the Kubernetes API. It provides non-blocking access to Kubernetes clusters from Python applications, built using the same OpenAPI generator approach as the official Kubernetes Python client, but with full async/await support. The library is actively maintained, with releases frequently aligning with the Kubernetes project's own approximately three-times-a-year release cadence.

pip install kubernetes_asyncio

Common errors

error ModuleNotFoundError: No module named 'kubernetes_asyncio' ↓
cause The `kubernetes-asyncio` library has not been installed in your Python environment or the environment where your code is running.
fix
Install the library using pip: pip install kubernetes-asyncio
error ApiException: (401) Reason: Unauthorized ↓
cause Your application lacks the necessary authentication credentials or Kubernetes Role-Based Access Control (RBAC) permissions to access the requested resource in the Kubernetes cluster.
fix
Ensure config.load_kube_config() or config.load_incluster_config() is correctly called to load credentials, and verify that the associated Kubernetes user or service account has the required RBAC permissions for the API operations you are attempting.
error AttributeError: 'NoneType' object has no attribute 'status' ↓
cause This error typically occurs when an API call, such as `list_namespaced_pod`, returns `None` (e.g., if the resource doesn't exist, an error occurred during the API call, or the response was unexpected), and your code then tries to access an attribute (like `status`) on that `None` object.
fix
Always check if the result of an API call or an object in the returned list is None before attempting to access its attributes. For example: if ret and ret.items: for i in ret.items: if i.status: print(i.status.pod_ip)
error RuntimeWarning: coroutine '...' was never awaited ↓
cause You called an `async` function (a coroutine) from the `kubernetes-asyncio` client library but forgot to `await` its result, meaning the coroutine was created but never scheduled to run.
fix
Prepend the call to the async function with await. For example, change v1.list_pod_for_all_namespaces() to await v1.list_pod_for_all_namespaces(). Ensure your code is running within an asyncio event loop (e.g., asyncio.run(main())).
error AttributeError: 'NoneType' object has no attribute 'configuration' ↓
cause This error occurs when using `DynamicClient` if the `kubernetes-asyncio` client object passed to it was not properly initialized or `config.load_kube_config()` failed to load configuration, resulting in a `None` object.
fix
Ensure that config.load_kube_config() (or config.load_incluster_config()) is successfully awaited and returns a valid ApiClient or Configuration object before passing it to DynamicClient. For example: await config.load_kube_config(); client = kubernetes_asyncio.client.ApiClient(); dyn_client = DynamicClient(client)

Warnings

breaking The versioning scheme changed significantly with `v18.20.0`. The first two numbers of the library version now indicate the target Kubernetes API version (e.g., `18.20.x` for Kubernetes `v1.18.x`). This is a departure from standard semantic versioning for the library itself and can cause confusion regarding compatibility. ↓
fix Refer to the library's official documentation and release notes for specific version compatibility with Kubernetes API versions. Map the first two parts of `kubernetes_asyncio`'s version to the Kubernetes API version you are targeting.
gotcha On Microsoft Windows, the default `asyncio.SelectorEventLoop` might not support pipes and subprocesses, causing `exec_provider.py::ExecProvider` (used for client-go credentials plugins) to fail. This is a common footgun for Windows users. ↓
fix Explicitly set the event loop policy at the start of your application: `import asyncio; asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())`.
gotcha It is crucial to use `ApiClient` within an `async with` statement (i.e., as a context manager) to ensure that underlying HTTP sessions are properly closed and resources are released. Failing to do so can lead to resource leaks or unexpected behavior in long-running applications. ↓
fix Always initialize and use `ApiClient` objects like this: `async with ApiClient() as api: ...`
gotcha Loading the Kubernetes configuration via `load_kube_config()` can fail if the kube-config file is malformed or lacks essential keys like 'current-context'. This is a common setup issue when the configuration file is incomplete or incorrectly generated. ↓
fix Ensure your Kubernetes configuration file (e.g., `~/.kube/config`) is valid and contains the 'current-context' key. You can generate a valid config using `kubectl config view --raw` or ensure your environment variables (like `KUBECONFIG`) point to a correctly configured file.
gotcha `kubernetes_asyncio.config.load_kube_config()` requires a valid Kubernetes configuration file, which includes the `current-context` key, to be present and accessible. If the file is missing, empty, or malformed, it will raise a `ConfigException`. ↓
fix Ensure a valid Kubernetes configuration file exists and is accessible. This file must contain at least a `current-context` key. You can explicitly specify the config file path using `config.load_kube_config(config_file='path/to/kubeconfig')` or ensure it's in a default location like `~/.kube/config` or referenced by the `KUBECONFIG` environment variable.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 1.45s 71.8M
3.10 alpine (musl) - - 1.46s 72.2M
3.10 slim (glibc) wheel 6.3s 1.00s 75M
3.10 slim (glibc) - - 1.09s 75M
3.11 alpine (musl) wheel - 2.16s 78.9M
3.11 alpine (musl) - - 2.47s 79.3M
3.11 slim (glibc) wheel 5.2s 1.85s 82M
3.11 slim (glibc) - - 1.73s 83M
3.12 alpine (musl) wheel - 1.88s 70.0M
3.12 alpine (musl) - - 2.15s 70.4M
3.12 slim (glibc) wheel 4.7s 1.85s 73M
3.12 slim (glibc) - - 2.19s 74M
3.13 alpine (musl) wheel - 1.90s 68.7M
3.13 alpine (musl) - - 1.88s 69.0M
3.13 slim (glibc) wheel 4.9s 1.77s 72M
3.13 slim (glibc) - - 1.90s 72M
3.9 alpine (musl) wheel - 1.31s 68.4M
3.9 alpine (musl) - - 1.54s 68.5M
3.9 slim (glibc) wheel 7.2s 1.20s 72M
3.9 slim (glibc) - - 1.15s 72M

Imports

Quickstart last tested: 2026-04-24

This quickstart example demonstrates how to load Kubernetes configuration, create an API client using an async context manager, and then list all pods across all namespaces in your cluster.

import asyncio
from kubernetes_asyncio import client, config
from kubernetes_asyncio.client.api_client import ApiClient

async def main():
    # Configs can be loaded from default locations (e.g., ~/.kube/config)
    # or explicitly from a file, or in-cluster configuration.
    # No argument provided means it will try default locations.
    await config.load_kube_config()

    # Use the context manager to ensure http sessions are closed automatically
    async with ApiClient() as api:
        v1 = client.CoreV1Api(api)
        print("Listing pods with their IPs:")
        ret = await v1.list_pod_for_all_namespaces()
        for i in ret.items:
            print(f"{i.status.pod_ip}\t{i.metadata.namespace}\t{i.metadata.name}")

if __name__ == '__main__':
    asyncio.run(main())
last verified Tue May 12
next check Sat Jun 27