aioesphomeapi

What it is and what it does

aioesphomeapi is an async Python client for the ESPHome Native API protocol, enabling programmatic interaction with devices running ESPHome firmware. It handles connection management, encryption via the Noise protocol, and state subscription over an async event loop. The library depends on protobuf for message serialization, cryptography libraries for encryption, and zeroconf for device discovery.

Typical usage involves instantiating an APIClient with device hostname and port, establishing an encrypted connection with a pre-shared key, then querying device information or subscribing to state changes via callbacks. The package includes CLI tools for log watching and device discovery, and falls back gracefully to pure Python if the optional Cython extension cannot be built.

Use it for:

• Monitor and retrieve state from ESPHome sensors, switches, and lights in a home automation system.
• Subscribe to real-time state changes and trigger actions based on device events.
• Integrate ESPHome devices with external systems like InfluxDB or custom dashboards.
• Discover ESPHome devices on the local network and query their capabilities programmatically.
• Build automation workflows that read device telemetry and send control commands asynchronously.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Async Python client library for communicating with ESPHome devices over the Native API, supporting encrypted and plaintext connections.

Yes. Active maintenance (release within 1 day), no known vulnerabilities, permissive MIT license, and medium install friction with graceful fallback make this suitable for production ESPHome integrations. Install if you need to programmatically interact with ESPHome devices; the optional Cython extension is a nice-to-have but not required.

Install

aioesphomeapi on PyPI

pip install aioesphomeapi

uv add aioesphomeapi

poetry add aioesphomeapi

Installing aioesphomeapi

Before you install

Medium install friction due to optional Cython extension that requires a C compiler and Python development headers; falls back to pure Python if unavailable. Active maintenance with release within 1 day of query.

License in practice

MIT license permits commercial and private use with minimal restrictions; suitable for most projects.

Quickstart

import aioesphomeapi
import asyncio

async def main():
    api = aioesphomeapi.APIClient(
        "device.local",
        6053,
        noise_psk="YOUR_ENCRYPTION_KEY"
    )
    await api.connect(login=True)
    device_info = await api.device_info()
    print(device_info)

asyncio.run(main())

Requires ESPHome device with Native API component enabled; Python 3.11 or later.

Verify before relying

• Whether Cython extension provides measurable performance benefit for typical use cases.
• Compatibility with ESPHome versions prior to 2026.1.0 and password authentication support details.

Package facts

Evidence: aioesphomeapi-45.10.2-cp311-cp311-macosx_10_9_x86_64.whl; aioesphomeapi-45.10.2-cp311-cp311-macosx_11_0_arm64.whl; aioesphomeapi-45.10.2-cp311-cp311-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl; aioesphomeapi-45.10.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl; aioesphomeapi-45.10.2-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl; aioesphomeapi-45.10.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; aioesphomeapi-45.10.2-cp311-cp311-musllinux_1_2_aarch64.whl; aioesphomeapi-45.10.2-cp311-cp311-musllinux_1_2_armv7l.whl; aioesphomeapi-45.10.2-cp311-cp311-musllinux_1_2_i686.whl; aioesphomeapi-45.10.2-cp311-cp311-musllinux_1_2_x86_64.whl; aioesphomeapi-45.10.2-cp311-cp311-win32.whl; aioesphomeapi-45.10.2-cp311-cp311-win_amd64.whl; aioesphomeapi-45.10.2-cp312-cp312-macosx_10_13_x86_64.whl; aioesphomeapi-45.10.2-cp312-cp312-macosx_11_0_arm64.whl; aioesphomeapi-45.10.2-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl; aioesphomeapi-45.10.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl; aioesphomeapi-45.10.2-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl; aioesphomeapi-45.10.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; aioesphomeapi-45.10.2-cp312-cp312-musllinux_1_2_aarch64.whl; aioesphomeapi-45.10.2-cp312-cp312-musllinux_1_2_armv7l.whl

Tags

More Networking packages