Chapter 1 · Install ESPHome 5 min

Docker

Run ESPHome in a Docker container - isolated, reproducible, no Python needed.

ghcr.io/esphome/esphome Official

Includes

Python + toolchain

Dashboard

Built-in web UI

Host install

Nothing needed

Your platform

Networking flags differ between Linux and Windows/macOS.

Install Docker

Install Docker Engine. Then add yourself to the docker group so you don't need sudo:

bashAdd user to docker group

sudo usermod -aG docker $USER
# Log out and back in for this to take effect

bashVerify Docker works

docker --version
docker run --rm hello-world

✓ You should see

Docker version 27.x.x, build abc1234 Hello from Docker! This message shows that your installation appears to be working correctly.

Run ESPHome

First, create a folder for your configs. Then pick how to run it:

bashCreate config folder

mkdir -p esphome-config

bashStart ESPHome dashboard

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

Runs in the foreground. Press Ctrl+C to stop. Good for trying things out - switch to Compose when you want it running permanently.

What each flag does (click to learn)

--net=host gives the container full LAN access including mDNS - this means OTA flashing and device discovery work exactly like a native install.

✓ You should see logs like

Starting ESPHome dashboard...

Loaded 0 device configs from /config

Dashboard is ready - http://0.0.0.0:6052

Open the dashboard

Open localhost:6052 →

You should see the ESPHome dashboard - an empty device list with a "+ New device" button at the bottom right. That's the same dashboard the Home Assistant Add-on users get.

ESPHome dashboard with + NEW DEVICE button

Heads up: USB flashing from Docker

The first flash must go over USB - OTA isn't available until ESPHome firmware is on the device. Docker needs access to the USB device for this.

Linux

Add --device=/dev/ttyUSB0 (or /dev/ttyACM0) to your docker run command. Check with ls /dev/tty*.

macOS / Windows

Docker Desktop can't pass through USB easily. Use web.esphome.io for the first flash instead - it runs in your browser via WebSerial. After that, all updates go over OTA through the Docker dashboard.

After the first USB flash, you'll never need USB again. All future updates happen wirelessly (OTA) through the ESPHome dashboard - this works perfectly from Docker.

Your progress

Docker cheatsheet

docker compose up -dStart in the background

docker compose downStop and remove the container

docker compose logs -fStream live logs

docker compose pullPull the latest ESPHome image

docker exec -it esphome bashShell into the running container

Checkpoint - Is the ESPHome dashboard reachable at localhost:6052?

If yes - you're done. Your configs live in the mounted folder and survive container restarts.

Yes - keep going Container starts but dashboard not loading