ESPHome

2026.4.2 verified Mon Apr 27 auth: no python

ESPHome is a system for configuring microcontrollers via simple YAML files and controlling them remotely through home automation systems. Current version 2026.4.2, requires Python >=3.11, <3.15. Release cadence is monthly.

pip install esphome

Common errors

error ModuleNotFoundError: No module named 'esphome' ↓

cause ESPHome is not installed.

fix

Run pip install esphome

error esphome: error: unrecognized arguments: --show-secrets ↓

cause Older CLI version does not support --show-secrets

fix

Upgrade esphome: pip install --upgrade esphome

error ERROR: Could not find a version that satisfies the requirement esphome (from versions: none) ↓

cause Python version out of range; ESPHome 2026.4.2 requires Python >=3.11, <3.15

fix

Use Python 3.11 or 3.12 (or 3.14 if available)

Warnings

gotcha ESPHome requires a running dashboard or manual compilation. Running pipelines without the dashboard may require special flags. ↓

fix Use esphome run <config.yaml> or esphome compile <config.yaml> instead of relying on dashboard.

breaking Breaking change: In 2026.x, the JSON config format changed. Old flasher scripts may break. ↓

fix Update your config parsing to handle new JSON schema or use esphome.run_command('config') to get correct output.

deprecated PlatformIO build system is deprecated in favor of ESP-IDF for ESP32. Using Arduino framework may cause compatibility warnings. ↓

fix Switch to esp-idf platform in your config or set legacy flag: esphome: { framework: { name: 'arduino', version: 'recommended' } }

gotcha Secrets are read from a 'secrets.yaml' file in the config directory. Programmatic usage may need to specify the path. ↓

fix Set SECRETS_PATH environment variable or copy secrets.yaml to working directory.

Imports

run_command
```
import esphome; esphome.run_command(['config', 'test.yaml'])
```
Use esphome.run_command() to invoke CLI programmatically; avoid subprocess calls.

secrets

wrong

from esphome.core import get_secret

correct

from esphome.secrets import get_secret

get_secret moved to esphome.secrets in recent versions.

Quickstart

Validate an ESPHome configuration programmatically.

import esphome
import yaml

# Basic configuration test
config = {
  'esphome': {
    'name': 'test-device',
    'platform': 'ESP32',
    'board': 'nodemcu-32s'
  },
  'wifi': {
    'ssid': 'MyWifi',
    'password': 'mypassword'
  }
}
# Validate configuration
result = esphome.run_command(['config', '--show-secrets', '-'], input=yaml.dump(config))
print(result)