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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.256s · 43.9MB
glibcpy 3.10–3.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.fixGenerate 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.fixMigrate 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.fixAdd `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.fixEnsure 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.fixAlways 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.
fixEnsure 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.
fixInstall 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.
fixVerify 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.
fixProvide 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.
fixEnsure 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.