{"id":888,"library":"kubernetes-asyncio","title":"Kubernetes Asynchronous Python Client","description":"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.","status":"active","version":"35.0.1","language":"python","source_language":"en","source_url":"https://github.com/tomplus/kubernetes_asyncio","tags":["kubernetes","asyncio","client","api","orchestration","cloud-native"],"install":[{"cmd":"pip install kubernetes_asyncio","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false}],"imports":[{"note":"The `kubernetes` package is the synchronous client. For asyncio-based applications, `kubernetes_asyncio` must be used.","wrong":"from kubernetes import client, config","symbol":"client, config","correct":"from kubernetes_asyncio import client, config"},{"note":"Required for creating an async HTTP session with the Kubernetes API.","symbol":"ApiClient","correct":"from kubernetes_asyncio.client.api_client import ApiClient"}],"quickstart":{"code":"import asyncio\nfrom kubernetes_asyncio import client, config\nfrom kubernetes_asyncio.client.api_client import ApiClient\n\nasync def main():\n    # Configs can be loaded from default locations (e.g., ~/.kube/config)\n    # or explicitly from a file, or in-cluster configuration.\n    # No argument provided means it will try default locations.\n    await config.load_kube_config()\n\n    # Use the context manager to ensure http sessions are closed automatically\n    async with ApiClient() as api:\n        v1 = client.CoreV1Api(api)\n        print(\"Listing pods with their IPs:\")\n        ret = await v1.list_pod_for_all_namespaces()\n        for i in ret.items:\n            print(f\"{i.status.pod_ip}\\t{i.metadata.namespace}\\t{i.metadata.name}\")\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=18.20.0"},{"fix":"Explicitly set the event loop policy at the start of your application: `import asyncio; asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())`.","message":"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.","severity":"gotcha","affected_versions":"All versions on Windows"},{"fix":"Always initialize and use `ApiClient` objects like this: `async with ApiClient() as api: ...`","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"`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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T20:52:59.470Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install kubernetes-asyncio`","cause":"The `kubernetes-asyncio` library has not been installed in your Python environment or the environment where your code is running.","error":"ModuleNotFoundError: No module named 'kubernetes_asyncio'"},{"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.","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.","error":"ApiException: (401) Reason: Unauthorized"},{"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)`","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.","error":"AttributeError: 'NoneType' object has no attribute 'status'"},{"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())`).","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.","error":"RuntimeWarning: coroutine '...' was never awaited"},{"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)`","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.","error":"AttributeError: 'NoneType' object has no attribute 'configuration'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"35.0.1","cli_name":"","cli_version":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"33.3.0","pypi_latest":"35.0.1","is_stale":true,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":1.45,"mem_mb":46.6,"disk_size":"71.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.46,"mem_mb":46.5,"disk_size":"72.2M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":6.3,"import_time_s":1,"mem_mb":46.6,"disk_size":"75M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.09,"mem_mb":46.5,"disk_size":"75M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":2.16,"mem_mb":52.4,"disk_size":"78.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.47,"mem_mb":52.5,"disk_size":"79.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":5.2,"import_time_s":1.85,"mem_mb":52.4,"disk_size":"82M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.73,"mem_mb":52.5,"disk_size":"83M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":1.88,"mem_mb":52,"disk_size":"70.0M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.15,"mem_mb":52,"disk_size":"70.4M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.7,"import_time_s":1.85,"mem_mb":52,"disk_size":"73M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.19,"mem_mb":52,"disk_size":"74M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":1.9,"mem_mb":52.2,"disk_size":"68.7M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.88,"mem_mb":52.2,"disk_size":"69.0M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.9,"import_time_s":1.77,"mem_mb":52.2,"disk_size":"72M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.9,"mem_mb":52.2,"disk_size":"72M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":1.31,"mem_mb":45.5,"disk_size":"68.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.54,"mem_mb":45.6,"disk_size":"68.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":7.2,"import_time_s":1.2,"mem_mb":45.5,"disk_size":"72M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"kubernetes_asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.15,"mem_mb":45.6,"disk_size":"72M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}