Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/esphome/esphome.io/llms.txt

Use this file to discover all available pages before exploring further.

The easiest way to get started with ESPHome is through the ESPHome Device Builder — a web-based interface for creating, editing, and installing device configurations. When you run Home Assistant, you can install it as a native add-on in just a few clicks. This guide walks you through the entire process from installation to your first working smart home device.

​
What You’ll Need

  • A running Home Assistant installation with add-on support (Home Assistant OS or Supervised)
  • An ESP32 or ESP8266 development board (e.g., NodeMCU, ESP32-DevKitC, Wemos D1 Mini)
  • A USB data cable to connect the board to your computer for the initial flash
  • Your Wi-Fi network name (SSID) and password
If your Home Assistant installation does not support add-ons (e.g., Home Assistant Container or Core), you can run the ESPHome Device Builder independently using Docker. See the Docker alternative section below.

​
Installing and Setting Up ESPHome

1

Install the ESPHome Device Builder Add-on

Open your Home Assistant instance and navigate to Settings → Add-ons → Add-on Store. Search for ESPHome Device Builder and click on it, or use the button below to open the add-on page directly:Open ESPHome add-on in Home AssistantOn the add-on page, click Install. Installation pulls the ESPHome container image and may take a minute or two depending on your internet speed.Once installation completes, click Start, then toggle Start on boot and Watchdog to keep the add-on running reliably. Finally, click Open Web UI to launch the Device Builder.
2

Open the ESPHome Device Builder Web UI

The Device Builder opens to the main dashboard. If this is your first time, you’ll see an empty configuration list and a prompt to create your first device.The dashboard displays all your ESPHome device configurations. For each entry you can:
  • EDIT — open the YAML configuration editor
  • LOGS — stream live logs from the device (via USB or Wi-Fi)
  • INSTALL — compile and push updated firmware to the device
  • UPDATE — appears when a newer ESPHome version is available for the device
ESPHome configuration files are stored in the <HOME_ASSISTANT_CONFIG>/esphome/ directory. For example, a device named bedroom-light is stored at /config/esphome/bedroom-light.yaml. To access these files via SSH, install the Home Assistant SSH add-on.
3

Create Your First Device Configuration

Click + New Device (or the equivalent prompt in the empty-state UI). The wizard offers three options:New Device Setup (recommended for beginners) The wizard guides you through selecting your microcontroller platform (ESP32, ESP8266, etc.), your specific board, and your Wi-Fi credentials. At the end, ESPHome generates a ready-to-use configuration file.Import from File Upload an existing .yaml or .yml ESPHome configuration. Useful for restoring a backup or migrating a configuration from another system. You can browse for a file or drag and drop it onto the dialog.Empty Configuration Creates a minimal skeleton for advanced users who want to write their configuration from scratch or paste one in from the ESPHome Device Database.After completing the wizard, your new device appears in the dashboard list.
4

Connect Your ESP Device via USB

Before ESPHome can install firmware onto a brand-new device, it needs a physical USB connection — at least for the very first flash.Connect your ESP board to the computer running Home Assistant (or to the computer your browser is running on — the web installer can flash locally). Use a USB data cable, not a charge-only cable.
The initial USB flash is the most common stumbling block for new users. Some cables only carry power and cannot transfer data. If the device is not detected, try a different cable before troubleshooting anything else. See the Physical Device Connection guide for full troubleshooting steps.
Once ESPHome is installed on your device, all future updates happen over the air (OTA) — no USB cable needed.
5

Install Firmware to Your Device

From the dashboard, click the overflow menu (⋮) on your new device entry and choose Install. The Install dialog presents several options:
  • Plug into this computer — flashes via the browser’s WebSerial API directly to a USB-connected device. Works on Chrome and Edge.
  • Plug into the computer running ESPHome — flashes via the server’s serial port (useful when the ESP is plugged into your Home Assistant machine).
  • Manual download — downloads a compiled .bin file that you can flash with ESPHome Web or esptool.
  • Wirelessly — available after the first installation; performs an OTA update over Wi-Fi.
ESPHome will compile your configuration (this takes 1–3 minutes on the first build; subsequent builds are faster due to caching) and then transfer the firmware.
If you run into compilation errors, try Clean Build Files from the overflow menu before reporting a bug. Stale build artifacts are a common cause of mysterious failures.
After flashing, enter your Wi-Fi credentials when prompted (if you didn’t include them in the wizard). The device will reboot, connect to your network, and begin broadcasting its presence.
6

Home Assistant Auto-Discovery

Once your ESPHome device is connected to Wi-Fi, Home Assistant will automatically discover it — usually within a minute. A notification will appear offering to add the new ESPHome integration.Open ESPHome integration in Home AssistantIf auto-discovery doesn’t appear after a few minutes, you can add the device manually:
  1. Go to Settings → Devices & Services → Add Integration
  2. Search for ESPHome
  3. Enter the device’s hostname (e.g., living-room-lamp.local) or its IP address
All sensors, switches, and other entities defined in your YAML configuration will appear automatically in Home Assistant’s UI.

​
Adding Components to Your Configuration

Once your device is running, click EDIT in the Device Builder to open the YAML editor. You can add any of ESPHome’s hundreds of components. Here are two quick examples: GPIO Switch — control a relay, LED, or any digital output: 
switch:
  - platform: gpio
    name: "Living Room Dehumidifier"
    pin: GPIO5
GPIO Binary Sensor — read a button, door sensor, or any digital input: 
binary_sensor:
  - platform: gpio
    name: "Living Room Window"
    pin:
      number: GPIO0
      inverted: true
      mode:
        input: true
        pullup: true
After editing, click SAVE and then INSTALL to push the updated firmware to your device wirelessly.
Saving the configuration file alone does not update the physical device. You must click INSTALL each time you want to apply changes.

​
Docker Alternative

If your Home Assistant setup doesn’t support add-ons, you can run the ESPHome Device Builder as a standalone Docker container: 
# docker-compose.yml
services:
  esphome:
    container_name: esphome
    image: ghcr.io/esphome/esphome
    volumes:
      - /path/to/esphome/config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: always
    privileged: true
    network_mode: host
    environment:
      - USERNAME=admin
      - PASSWORD=ChangeMe
Start it with docker compose up -d, then open http://<your-host>:6052 in your browser. The web interface is identical to the Home Assistant add-on.
Running ESPHome on WSL2? Store your config files inside the WSL2 filesystem (e.g., ~/esphome/config) rather than on a Windows-mounted drive (e.g., /mnt/c/...). Accessing Windows drives from WSL2 can make builds 10× slower due to filesystem overhead.

​
Where to Go Next

You’ve installed ESPHome, created your first device configuration, and connected it to Home Assistant. Here are some natural next steps:

Build docs developers (and LLMs) love

Get started for freeTalk to us