Registry / devops / kubernetes-asyncio

kubernetes-asyncio

library36.1.0pypypi✓ verified 25d ago

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.

devops http-networking

pip install kubernetes_asyncio

package ↗

INSTALL

IMPORT

SIG · KUBERNETES-ASYNCIO

kubernetes-asyncio

devopspythonv36.1.0

Install

5.9s avg

Import

1691ms

Disk

76MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v36.1.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.95 runs

installs and imports cleanly · install 0.0s · import 1.812s · 75.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 5.9s · import 1.570s · 78MB

76MB installed

● package 76MB

Code

Verified usage

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

client, config

✓ from kubernetes_asyncio import client, config

✗ from kubernetes import client, config

The `kubernetes` package is the synchronous client. For asyncio-based applications, `kubernetes_asyncio` must be used.

ApiClient

✓ from kubernetes_asyncio.client.api_client import ApiClient

Required for creating an async HTTP session with the Kubernetes API.

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())

Debug

Known issues

breakingThe 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.

affects: >=18.20.0

gotchaOn 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())`.

affects: All versions on Windows

gotchaIt 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: ...`

affects: All versions

gotchaLoading 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.

affects: All versions

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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'kubernetes_asyncio'

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`

ApiException: (401) Reason: Unauthorized

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.

AttributeError: 'NoneType' object has no attribute 'status'

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)`

RuntimeWarning: coroutine '...' was never awaited

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())`).

AttributeError: 'NoneType' object has no attribute 'configuration'

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)`

Upgrade

Version history

36.1.0latest on PyPI · released Jun 4, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.10 or newer.

Agent activity

12 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/kubernetes-asyncio/ ↗