ESPHome Dashboard

20260425.0 verified Mon Apr 27 auth: no python

ESPHome Dashboard is the web-based UI for managing ESPHome devices. It provides device discovery, configuration editing, firmware building, and OTA updates. The current version as of April 2026 is 20260425.0, with frequent releases tied to ESPHome updates (weekly to monthly).

pip install esphome-dashboard

Common errors

error ESPHOME_DASHBOARD: error: unrecognized arguments: ↓

cause Outdated command-line arguments; newer versions use flags like --port instead of positional arguments.

fix

Check current usage: esphome dashboard --help or refer to docs.

error ModuleNotFoundError: No module named 'esphome_dashboard' ↓

cause Package not installed or installed as esphome-dashboard (with hyphen) which is the PyPI name, but import uses underscore.

fix

Install: pip install esphome-dashboard, then import: from esphome_dashboard import start_web_server

error fatal: unable to access 'https://github.com/esphome/dashboard.git/': Could not resolve host ↓

cause Network issue when dashboard tries to build firmware by cloning ESPHome repo.

fix

Ensure network access and that git is installed and configured.

Warnings

gotcha The dashboard requires a running ESPHome instance (esphome dashboard command) and does not operate standalone as a Python library. ↓

fix Use the esphome CLI (esphome dashboard) to launch the dashboard instead of importing esphome_dashboard directly.

gotcha The package esphome-dashboard on PyPI is a Python wrapper that launches a bundled Node.js server, not a pure Python library. ↓

fix Do not expect to import Python classes; the package primarily launches a subprocess.

deprecated The dashboard configuration via YAML file (dashboard_import) is deprecated in favor of environment variables and command-line flags. ↓

fix Use command-line arguments (e.g., --port, --password) or env vars (DASHBOARD_PASSWORD, ESPHOME_DASHBOARD_USE_IMPROV) instead.

gotcha The dashboard's bundled Node.js server may conflict with system Node.js or require additional system dependencies (e.g., libnss3). ↓

fix Install dependencies: sudo apt install libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libdbus-1-3 libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2

Imports

start_web_server

from esphome_dashboard import start_web_server

Quickstart

Starts the ESPHome dashboard web server. Requires configuration directory path; optionally set password via DASHBOARD_PASSWORD env var.

import os
from esphome_dashboard import start_web_server

# Start the dashboard (configuration via environment variables)
start_web_server(
    configuration_path=os.environ.get('CONFIG_PATH', '/config'),
    password=os.environ.get('DASHBOARD_PASSWORD', '')
)