---
id: aioesphomeapi
version: "45.10.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# aioesphomeapi — Python API for interacting with ESPHome devices.

License: permissive · Maintenance: active · Downloads: 1.1M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 1.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

esphome device communication, async esphome api client, esphome native api python, esphome device control, esphome state subscription, esphome encryption support, esphome device discovery, esphome, home-automation, async-io

[View on SkillFed](https://skillfed.io/packages/aioesphomeapi) · [View on PyPI](https://pypi.org/project/aioesphomeapi/)