Registry / http-networking / aioesphomeapi

aioesphomeapi

JSON →
library46.2.1pypypi✓ verified 22d ago

aioesphomeapi is an asynchronous Python API client designed for interacting with devices running ESPHome firmware. It provides a way for Python applications, notably Home Assistant, to communicate with ESPHome devices using their native API for real-time control and monitoring. The library is actively maintained with frequent updates, often aligning with ESPHome and Home Assistant releases. The current version is 44.13.3.

pip install aioesphomeapi
INSTALL
IMPORT
SIG · AIOESPHOMEAPI
A
aioesphomeapi
http-networkingpythonv46.2.1
Install
5.2s avg
Import
962ms
Disk
45MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v36.0.1 · 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.103.910 runs
installs and imports cleanly · install 0.0s · import 1.256s · 43.9MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 5.2s · import 0.668s · 45MB
45MB installed
● package 45MB
Code
Verified usage

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

APIClient
from aioesphomeapi import APIClient
DeviceInfo
from aioesphomeapi.model import DeviceInfo
from aioesphomeapi import DeviceInfo
Model classes like DeviceInfo are found within the `aioesphomeapi.model` submodule.

This quickstart demonstrates how to connect to an ESPHome device, retrieve its API version, device information, and a list of available entities. It prioritizes using `noise_psk` for secure connections, falling back to an optional password (now deprecated). Ensure the ESPHome device has the Native API enabled in its configuration and provide the correct host, port, and authentication details via environment variables.

import aioesphomeapi import asyncio import os async def main(): host = os.environ.get('ESPHOME_HOST', 'device.local') port = int(os.environ.get('ESPHOME_PORT', 6053)) noise_psk = os.environ.get('ESPHOME_NOISE_PSK', '') # Recommended for secure communication password = os.environ.get('ESPHOME_PASSWORD', '') # Deprecated, use noise_psk if not noise_psk and not password: print("Warning: No encryption key or password provided. Connection might fail or be insecure.") # Establish connection api = aioesphomeapi.APIClient( host, port, noise_psk=noise_psk if noise_psk else None, password=password if password else None ) try: await api.connect(login=True) print(f"Successfully connected to {host}:{port}") # Get API version of the device's firmware print(f"API Version: {api.api_version}") # Show device details device_info = await api.device_info() print(f"Device Info: {device_info.name} ({device_info.mac_address})") # List all entities of the device entities = await api.list_entities_services() print(f"Number of entities: {len(entities.entities)}") # for entity in entities.entities: # print(f" - {entity.name} ({entity.key})") except aioesphomeapi.APIConnectionError as e: print(f"Connection error: {e}") except Exception as e: print(f"An unexpected error occurred: {e}") finally: if api.is_connected: await api.disconnect() print("Disconnected.") if __name__ == "__main__": asyncio.run(main())
Debug
Known issues
breakingPassword authentication was removed in ESPHome 2026.1.0. Devices running this version or newer will only accept connections using a `noise_psk` (encryption key). Attempting to connect with only a password will fail.
fix
Generate an encryption key (noise_psk) for your ESPHome device and update your client code to use the `noise_psk` argument instead of `password` in `APIClient`. Example: `api = APIClient(host, port, noise_psk='YOUR_ENCRYPTION_KEY')`.
affects: ESPHome >= 2026.1.0
deprecatedThe `password` argument in `aioesphomeapi.APIClient` is deprecated. While it still works for older ESPHome devices, it's recommended to switch to `noise_psk` for security and future compatibility.
fix
Migrate to using `noise_psk` for authentication. Configure `api: encryption: key: !secret api_encryption_key` in your ESPHome device's YAML configuration and pass the generated key as `noise_psk` to `APIClient`.
affects: All versions where `password` is used with ESPHome < 2026.1.0
gotchaThe ESPHome device *must* have the Native API component enabled in its YAML configuration for `aioesphomeapi` to connect. Without it, the device will not be listening for API connections.
fix
Add `api:` (or `api: encryption: key: !secret api_encryption_key`) to your ESPHome device's configuration YAML and re-flash the device.
affects: All
gotchaFor optimal performance, `aioesphomeapi` can use an optional Cython extension. If this extension cannot be built (e.g., due to missing C compiler or Python development headers), the library will silently fall back to a pure Python implementation, which may be slower.
fix
Ensure you have a C compiler (e.g., GCC or Clang) and Python development headers installed on your system. Alternatively, set the environment variable `SKIP_CYTHON=1` to forcefully disable the Cython extension.
affects: All
gotcha`aioesphomeapi` uses Protocol Buffers for communication and must be kept consistent with the ESPHome firmware version on your devices. Breaking changes in the ESPHome API protocol require corresponding updates in `aioesphomeapi` to maintain compatibility.
fix
Always aim to keep your `aioesphomeapi` library version updated, especially when updating ESPHome firmware on your devices or Home Assistant instances that rely on `aioesphomeapi`.
affects: All
Errors
Common errors & fixes
ImportError: /usr/local/lib/python3.9/dist-packages/google/protobuf/pyext/_message.cpython-39-x86_64-linux-gnu.so: undefined symbol: _ZN6google8protobuf2io26CopyingOutputStreamAdaptorC2EPNS1_1
This error occurs due to a mismatch between the installed versions of the 'protobuf' library and the 'aioesphomeapi' package, leading to compatibility issues.
fix
Ensure that both 'protobuf' and 'aioesphomeapi' are updated to compatible versions by running 'pip install --upgrade protobuf aioesphomeapi'.
ModuleNotFoundError: No module named 'aioesphomeapi'
This error indicates that the 'aioesphomeapi' package is not installed in the Python environment.
fix
Install the 'aioesphomeapi' package using 'pip install aioesphomeapi'.
AttributeError: module 'aioesphomeapi' has no attribute 'APIClient'
This error suggests that the 'APIClient' class is not found within the 'aioesphomeapi' module, possibly due to an incorrect import statement or a version mismatch.
fix
Verify that you are using the correct import statement: 'from aioesphomeapi import APIClient', and ensure that the 'aioesphomeapi' package is up to date.
TypeError: __init__() missing 1 required positional argument: 'password'
This error occurs when initializing the 'APIClient' class without providing the required 'password' argument.
fix
Provide the 'password' argument when initializing 'APIClient': 'api = APIClient('device.local', 6053, password='YourPassword')'.
ConnectionRefusedError: [Errno 111] Connection refused
This error indicates that the connection to the ESPHome device was refused, possibly because the device is offline or the API component is not enabled.
fix
Ensure that the ESPHome device is powered on, connected to the network, and that the 'api' component is correctly configured in the device's ESPHome configuration.
Upgrade
Version history
46.2.1latest on PyPI · released Aug 26, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
70 hits · last 30 days
node
56
Perplexity
1
OpenAI (training)
1
Resources