Getting Started with ESPHome from the Command Line

ESPHome has a full-featured command-line interface that lets you create configurations, compile firmware, flash devices, and stream logs — all from your terminal. This guide is ideal if you prefer scripting, want to integrate ESPHome into a CI pipeline, or simply like staying in the command line. If you’d rather use a web UI, see the Home Assistant add-on guide.

Install ESPHome

See Installing ESPHome for the full platform-by-platform walkthrough. The quick versions are below.

# Create and activate a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install ESPHome
pip install esphome

# Verify
esphome version

Docker Compose

If you prefer Docker Compose, create a docker-compose.yml in your project directory:

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 the container with docker compose up -d. The ESPHome Device Builder web interface is then available at http://localhost:6052.

On macOS, Docker cannot pass USB devices through to containers due to hypervisor limitations. You will not be able to flash ESP devices via USB on Mac. OTA (wireless) updates and all other features work normally. Web-based flashing via ESPHome Web is also available as an alternative.

If you back your Docker config volume with an NFS share, mount it with the nolock option. Without it, PlatformIO (used internally by ESPHome) may hang on startup. See platformio-core#3089.

Connect Your ESP Device

For the very first firmware install, you need to connect your ESP32 or ESP8266 to your computer via a USB data cable.

Initial installation via USB is the most involved step for new users — especially picking the right serial port. Later updates happen wirelessly over OTA. Follow the Physical Device Connection guide for step-by-step serial port identification on each OS.

On Linux, your device typically appears as /dev/ttyUSB0 or /dev/ttyACM0. You may need to add your user to the dialout group:

sudo usermod -a -G dialout $USER
# Log out and back in for this to take effect

On macOS, look for /dev/cu.usbserial-* or /dev/cu.SLAB_USBtoUART. On Windows, check Device Manager for a COM port (e.g., COM3).

Create a Configuration

ESPHome’s setup wizard interactively creates a new configuration file. Run it with the name you want to give your config:

esphome wizard livingroom.yaml

With Docker:

docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome wizard livingroom.yaml

The wizard asks for:

Your board type (ESP32, ESP8266, etc.)
Your specific board variant
Your Wi-Fi SSID and password

At the end, livingroom.yaml is created in the current directory. It will look roughly like this:

esphome:
  name: livingroom
  friendly_name: Living Room

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:

api:
  encryption:
    key: "your-generated-api-key"

ota:
  - platform: esphome
    password: "your-ota-password"

wifi:
  ssid: "YourWiFiSSID"
  password: "YourWiFiPassword"

  ap:
    ssid: "Livingroom Fallback Hotspot"
    password: "fallback-password"

Add Components

Open livingroom.yaml in your editor and add components. For example, a GPIO switch and a GPIO binary sensor:

switch:
  - platform: gpio
    name: "Living Room Dehumidifier"
    pin: GPIO5

binary_sensor:
  - platform: gpio
    name: "Living Room Window"
    pin:
      number: GPIO0
      inverted: true
      mode:
        input: true
        pullup: true

ESPHome will automatically translate board-specific pin aliases (e.g., D1 on a NodeMCU) to the correct GPIO number, so you can use either format.

Compile and Flash

Once your configuration is ready, compile and flash it with a single command:

esphome run livingroom.yaml

ESPHome will:

Validate the configuration YAML
Generate C++ source code
Compile the firmware via PlatformIO
Detect a connected serial device and flash it
Switch to streaming live logs once the device boots

The first compilation takes 2–5 minutes as PlatformIO downloads the required toolchain and libraries. Subsequent builds are much faster due to caching. With Docker on Linux (passing the USB device through):

docker run --rm --privileged \
  -v "${PWD}":/config \
  --device=/dev/ttyUSB0 \
  -it ghcr.io/esphome/esphome run livingroom.yaml

Alternatively, you can download the compiled .bin and flash it manually using ESPHome Web or esptool. See the FAQ for details.

View Logs

After the first flash, you can stream logs over Wi-Fi (no USB required) at any time:

esphome logs livingroom.yaml

With Docker:

docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome logs livingroom.yaml

ESPHome resolves the device hostname (e.g., livingroom.local) via mDNS and connects automatically. If your network blocks mDNS, pass --device <IP_ADDRESS> to specify the IP directly.

OTA Updates

After the initial USB flash, every subsequent update is delivered over the air. Just run the same run command — ESPHome detects that the device is already on the network and performs a wireless OTA update automatically:

# Edit your config, then deploy wirelessly
esphome run livingroom.yaml

With Docker:

docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome run livingroom.yaml

No USB cable, no physical access needed. 🎉

Home Assistant Discovery

Once your device is on the network, Home Assistant will discover it automatically (within about 5 minutes). Go to Settings → Devices & Services and you should see the ESPHome integration offering to add your new device. To add it manually, click Add Integration, search for ESPHome, and enter livingroom.local (replace livingroom with your device name) or the device’s IP address.

Bonus: ESPHome Device Builder

The ESPHome Device Builder web UI (the same interface available in the Home Assistant add-on) can also be run standalone:

# Install dashboard extras
pip install tornado esptool

# Start the web UI (config/ is the directory with your YAML files)
esphome dashboard config/

With Docker (Linux — host networking required for device online-status indicators):

docker run --rm --net=host -v "${PWD}":/config -it ghcr.io/esphome/esphome

With Docker (macOS — host networking doesn’t work, use ping-based discovery instead):

docker run --rm -p 6052:6052 \
  -e ESPHOME_DASHBOARD_USE_PING=true \
  -v "${PWD}":/config \
  -it ghcr.io/esphome/esphome

Open http://localhost:6052 in your browser. Log level can be controlled with the ESPHOME_LOG_LEVEL environment variable (default: INFO).

Where to Go Next

Component Reference — explore all available sensors, outputs, displays, and integrations
CLI Reference — full documentation for all esphome subcommands and flags
Home Assistant Guide — if you’d prefer the web UI experience
Security Best Practices — harden your devices for production use
FAQ — solutions to common problems

Introduction

Core Concepts

Guides

Cookbook

Getting Started with ESPHome from the Command Line

Install ESPHome

Docker Compose

Connect Your ESP Device

Create a Configuration

Add Components

Compile and Flash

View Logs

OTA Updates

Home Assistant Discovery

Bonus: ESPHome Device Builder

Where to Go Next

Build docs developers (and LLMs) love

Introduction

Core Concepts

Guides

Cookbook

Documentation Index

​Install ESPHome

​Docker Compose

​Connect Your ESP Device

​Create a Configuration

​Add Components

​Compile and Flash

​View Logs

​OTA Updates

​Home Assistant Discovery

​Bonus: ESPHome Device Builder

​Where to Go Next

Build docs developers (and LLMs) love

Install ESPHome

Docker Compose

Connect Your ESP Device

Create a Configuration

Add Components

Compile and Flash

View Logs

OTA Updates

Home Assistant Discovery

Bonus: ESPHome Device Builder

Where to Go Next