How to install ESPHome with Docker to manage ESP32 and ESP8266 devices

ESPHome with Docker lets you run the ESPHome dashboard in a container and manage ESP32 or ESP8266 smart devices from a single location. After installation, you can create YAML configuration files, compile firmware, flash your first device, update it over Wi-Fi, and connect sensors, switches, lights, or relays to your smart home setup.

To install ESPHome with Docker, prepare a server with Docker and Docker Compose, create a persistent configuration folder, start the ESPHome container, and open the dashboard on port 6052. You can also deploy ESPHome faster with Hostinger’s Docker template if you want a preconfigured VPS setup instead of writing the Docker configuration manually. Once ESPHome is running, use it to create your first device configuration, flash an ESP32 or ESP8266 board, and manage future firmware updates from the dashboard.

What do you need before installing ESPHome with Docker?

Before installing ESPHome with Docker, prepare a server with Docker, an ESP32 or ESP8266 board, Wi-Fi credentials, and a persistent folder for ESPHome configuration files. These requirements let ESPHome run as a container, store device YAML files safely, and connect flashed devices to your network.

You need:

1. A server or local machine with Docker installed – ESPHome can run on a VPS, Linux server, Raspberry Pi, or local computer that supports Docker. For a persistent setup, a VPS or always-on Linux machine is better than a personal laptop.
2. Docker Compose – Docker Compose is recommended for long-term ESPHome management because it keeps the container configuration in one reusable file and restarts ESPHome after server reboots.
3. An ESP32 or ESP8266 device – ESPHome supports ESP-based boards such as ESP32 DevKit, NodeMCU ESP8266, Wemos D1 Mini, and many ready-made smart home devices that use ESP chips.
4. A USB data cable – The first firmware installation usually requires connecting the ESP device to the machine running ESPHome. Use a data-transfer cable, not a charging cable.
5. Wi-Fi network credentials – ESPHome needs your Wi-Fi SSID and password so the ESP device can connect to the network after flashing.
6. A persistent ESPHome configuration folder – This folder stores YAML files, secrets, build files, and device settings. In Docker, it is usually mounted to the container as /config.
7. Access to port 6052 – ESPHome uses it for the dashboard. Make sure this port is available and allowed by your server firewall.
8. Optional Home Assistant installation – Home Assistant is not required for ESPHome, but it is useful if you want to control ESPHome sensors, switches, lights, and other smart devices from a home automation dashboard.
9. Optional Hostinger VPS with the ESPHome Docker template – Hostinger’s Docker template is useful if you want to deploy ESPHome on an always-on VPS without manually creating the Docker setup.

Check the USB flashing requirement before choosing where to run ESPHome. A remote VPS is useful for keeping the dashboard online, storing YAML files, and managing OTA updates, but it cannot physically connect to an ESP board in your home unless you use another flashing method first. For many setups, the practical workflow is to flash the device locally the first time, then use the Docker-based ESPHome dashboard for wireless updates and ongoing management.

How to install ESPHome with Docker

ESPHome runs in Docker as a containerized Device Builder, letting you create, edit, compile, and manage ESP32 or ESP8266 firmware from a web dashboard. The Docker setup requires a persistent configuration folder, the official ESPHome image, and access to port 6052.

1. Create an ESPHome configuration directory

First, create a dedicated directory for ESPHome. This folder stores your YAML configuration files, device secrets, firmware build files, and dashboard data.

mkdir -p ~/esphome/config
cd ~/esphome

ESPHome stores its project files inside the container’s /config directory. Mapping ~/esphome/config to /config keeps your device configurations available after the container restarts or updates.

2. Run ESPHome with Docker CLI

Use the official ESPHome Docker image to start the dashboard:

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

This command starts ESPHome in the foreground. Here is what each option does:

This method works well for testing ESPHome or creating your first device configuration. For a long-term setup, use Docker Compose instead.

3. Install ESPHome with Docker Compose

Docker Compose keeps ESPHome running as a persistent service. Create a docker-compose.yml file inside the ~/esphome directory:

nano docker-compose.yml

Add the following configuration:

services:
esphome:
container_name: esphome
image: ghcr.io/esphome/esphome
volumes:
- ./config:/config
- /etc/localtime:/etc/localtime:ro
restart: always
privileged: true
network_mode: host

Save the file and start ESPHome:

docker compose up -d

Docker Compose pulls the ESPHome image and runs the container in the background. The restart: always setting automatically starts ESPHome again after a server reboot, while network_mode: host helps the dashboard detect ESP devices on the same network.

To check whether the container is running, use:

docker ps

You should see a container named esphome in the output.

4. Open the ESPHome dashboard

After the container starts, open the ESPHome dashboard in your browser:

http://SERVER-IP:6052

Replace SERVER-IP with your server’s IP address. If you installed ESPHome on your local machine, use:

http://localhost:6052

The dashboard is where you create ESPHome YAML files, compile firmware, install updates, and view device logs.

5. Check ESPHome container logs

If the dashboard does not load, check the container logs:

docker logs esphome

For a live log view, run:

docker logs -f esphome

The logs help identify startup errors, permission issues, missing volumes, or network problems.

6. Update ESPHome later

To update ESPHome with Docker Compose, pull the latest image and recreate the container:

docker compose pull
docker compose up -d

Your YAML files remain available because they are stored in the mapped ./config directory, not inside the container itself.

7. Stop or restart ESPHome

Use these commands to manage the ESPHome container:

docker compose restart

docker compose stop

docker compose up -d

Restart ESPHome after changing Docker settings, updating the image, or troubleshooting dashboard access.

How to deploy ESPHome faster with Hostinger’s Docker template

Hostinger’s ESPHome Docker template deploys ESPHome on a VPS without manually pulling the Docker image, writing a Compose file, or configuring the container from scratch. This setup is useful if you want an always-on ESPHome dashboard for managing ESP32 and ESP8266 devices remotely.

Follow these steps to deploy ESPHome with Hostinger’s Docker template:

1. Log in to hPanel.
2. Go to VPS and choose your server.
3. Open OS & Panel.
4. Select Docker as the VPS template category.
5. Choose the ESPHome Docker template.
6. Reinstall or deploy the template on your VPS.
7. Wait until the installation finishes.
8. Open the ESPHome dashboard using your VPS IP address and port 6052:

http://SERVER-IP:6052

Replace SERVER-IP with your VPS IP address.

Using Hostinger’s Docker template removes the manual Docker setup steps. Instead of creating a configuration directory, writing a docker-compose.yml file, and starting the container yourself, the template installs ESPHome in a preconfigured Docker environment.

This is especially useful for ESP device management because ESPHome benefits from a server that stays online. With ESPHome running on a VPS, you can keep your device configuration files in one place, access the dashboard from different devices, check container logs, and manage firmware updates without relying on a laptop or local workstation.

After deployment, use the ESPHome dashboard to create YAML configurations, compile firmware, and manage ESP32 or ESP8266 devices. The first firmware installation may still require a USB connection or another supported flashing method, but later updates can usually be installed over the air once the device is connected to the network.

How to create your first ESPHome device configuration

An ESPHome device configuration is a YAML file that tells ESPHome how to build firmware for a specific ESP32 or ESP8266 board. The configuration defines the board type, Wi-Fi connection, ESPHome API, over-the-air updates, and the components the device controls or monitors.

1. Open the ESPHome dashboard

Open your ESPHome dashboard in a browser:

http://SERVER-IP:6052

Replace SERVER-IP with your VPS or server IP address. If ESPHome runs on your local machine, use:

http://localhost:6052

The dashboard lets you create, edit, validate, compile, and install ESPHome configurations.

2. Create a new device

In the ESPHome dashboard, click New Device. Enter a clear device name that describes the device location or function, such as living-room-sensor, bedroom-plug, or garage-door-sensor.

Use lowercase letters and hyphens for device names. Consistent names make ESPHome configurations easier to manage when you add more ESP32 or ESP8266 devices later.

3. Select the ESP board type

Choose the board that matches your physical device. ESPHome uses this board setting to compile firmware with the correct platform settings and pin layout.

For example, use esp32dev for a generic ESP32 development board, nodemcuv2 for many NodeMCU ESP8266 boards, or the matching board option for your specific device. Choose ESP32 if the device needs more memory, Bluetooth support, or more GPIO pins. Choose ESP8266 for simpler sensors, relays, or low-cost Wi-Fi projects.

4. Enter Wi-Fi credentials

Add the Wi-Fi network name and password that the ESP device will use after flashing. ESPHome can store these values directly in the device YAML file, but using secrets.yaml is cleaner when managing multiple devices.

A basic Wi-Fi configuration looks like this:

wifi:
ssid: "Your_WiFi_Name"
password: "Your_WiFi_Password"

For better configuration management, store credentials in secrets.yaml:

wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password

Then add the actual values to secrets.yaml:

wifi_ssid: "Your_WiFi_Name"
wifi_password: "Your_WiFi_Password"

This keeps Wi-Fi credentials separate from each device file.

5. Review the generated YAML file

After you complete the setup wizard, ESPHome creates a YAML file for the device. A basic ESP32 configuration may look like this:

esphome:
name: living-room-sensor
esp32:
board: esp32dev
framework:
type: arduino
logger:
api:
ota:
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password

The esphome section defines the device name. The esp32 or esp8266 section defines the chip platform and board type. The logger section enables device logs, api allows Home Assistant communication, ota enables future wireless firmware updates, and wifi connects the device to your network.

For an ESP8266 board, replace the ESP32 section with:

esp8266:
board: nodemcuv2

Use the platform section that matches your device. A mismatched board setting can cause failed builds, incorrect GPIO behavior, or unstable firmware.

6. Add a basic component

After the base configuration works, add a component that matches your device function. For example, this configuration adds a GPIO switch for a relay, lamp, or fan:

switch:
platform: gpio
name: "Living Room Lamp"
pin: GPIO5

This tells ESPHome to control the GPIO5 pin as a switch named Living Room Lamp. After the device is added to Home Assistant, the switch appears as a controllable entity.

For a simple status sensor, add a Wi-Fi signal sensor:

sensor:
platform: wifi_signal
name: "Living Room Sensor WiFi Signal"
update_interval: 60s

This sensor reports the device’s Wi-Fi signal strength every 60 seconds, which helps confirm whether the ESP device has a stable network connection.

7. Validate the configuration

Before compiling firmware, validate the YAML file from the ESPHome dashboard. You can also validate it from the command line:

docker run --rm -v "$PWD/config":/config -it ghcr.io/esphome/esphome config living-room-sensor.yaml

Replace living-room-sensor.yaml with your configuration file name.

Validation checks the YAML syntax, board settings, component configuration, and required fields. Fix any errors before compiling or flashing the firmware.

8. Save the configuration for future device management

Each ESPHome device should have its own YAML file in the /config directory:

config/
living-room-sensor.yaml
bedroom-plug.yaml
garage-door-sensor.yaml
kitchen-light-switch.yaml
secrets.yaml

This structure keeps ESP device management organized. When you need to change a sensor, rename an entity, adjust a GPIO pin, or add Home Assistant integration, edit the relevant YAML file and reinstall the firmware from the ESPHome dashboard.

How to flash ESP32 and ESP8266 devices with ESPHome

Flashing installs the ESPHome firmware on your ESP32 or ESP8266 device. The first installation usually requires a USB connection, while later firmware changes can be installed over the air if OTA is enabled and the device is connected to Wi-Fi.

1. Connect the ESP device to your server

Connect the ESP32 or ESP8266 board to the machine running Docker. Use a USB cable that supports data transfer, not a charge-only cable.

Then check which serial port the device uses:

ls /dev/ttyUSB*

If that command returns no device, try:

ls /dev/ttyACM*

Most ESP boards appear as /dev/ttyUSB0 or /dev/ttyACM0. Use the detected path in the flashing command.

2. Flash the device from the ESPHome dashboard

Open the ESPHome dashboard:

http://SERVER-IP:6052

Find the device configuration you created earlier, then click Install. ESPHome will ask how you want to install the firmware.

Choose Plug into the computer running ESPHome Dashboard if the ESP board is connected directly to the Docker host. ESPHome will compile the firmware, access the USB serial device, and install the firmware on the board.

If the dashboard does not detect the board, use the command-line method instead.

3. Flash the device with Docker CLI

Run the ESPHome container with USB device access:

docker run --rm --privileged
-v "$PWD/config":/config
--device=/dev/ttyUSB0
-it ghcr.io/esphome/esphome run living-room-sensor.yaml

Replace /dev/ttyUSB0 with your detected serial device. Replace living-room-sensor.yaml with your ESPHome configuration file.

This command validates the YAML file, compiles the firmware, uploads it to the ESP board, and opens the device logs after installation. The –privileged option gives the container the permissions needed to access the USB device.

4. Flash the device with Docker Compose

If you installed ESPHome with Docker Compose, add the USB device to your docker-compose.yml file:

services:
esphome:
container_name: esphome
image: ghcr.io/esphome/esphome
volumes:
- ./config:/config
- /etc/localtime:/etc/localtime:ro
restart: always
privileged: true
devices:
- /dev/ttyUSB0:/dev/ttyUSB0
network_mode: host

Restart the container after saving the file:

docker compose up -d

Then return to the ESPHome dashboard and install the firmware again. ESPHome should now be able to access the USB-connected board.

5. Put the board into bootloader mode if flashing fails

Some ESP32 and ESP8266 boards enter flashing mode automatically. Others require manual bootloader mode.

Press and hold the BOOT or FLASH button on the board, start the installation, and release the button when ESPHome begins uploading the firmware. If the upload still fails, disconnect the board, reconnect it, and try again with a different USB cable or USB port.

6. Use OTA updates after the first flash

After the first successful flash, ESPHome connects the device to Wi-Fi using the credentials in your YAML configuration. If the ota section is enabled, future firmware updates can be installed wirelessly from the dashboard.

To update the device later, edit the YAML file, click Install, and choose Wirelessly. ESPHome will compile the new firmware and send it to the device over the network.

OTA updates simplify ESP device management because you no longer need to physically reconnect each board after the first installation. Keep USB access available for recovery, especially when changing Wi-Fi credentials, board settings, or OTA configuration.

How to manage ESP devices after installation

After installation, ESPHome manages ESP32 and ESP8266 devices through the dashboard and each device’s YAML configuration file. Use the dashboard to edit configurations, validate changes, compile firmware, install updates, and check device logs.

Each ESP device should have its own YAML file in the /config directory:

config/
living-room-sensor.yaml
bedroom-plug.yaml
garage-door-relay.yaml
secrets.yaml

Use clear names that describe the device location or function. For example, garage-door-relay.yaml is easier to manage than esp8266-1.yaml when your setup grows.

To update a device, open its YAML file, change the relevant component, validate the configuration, and install the new firmware. For example, this GPIO switch exposes a relay as a controllable device:

switch:
platform: gpio
name: "Garage Door Relay"
pin: GPIO5

After the first USB flash, most future changes can be installed over the air if OTA is enabled and the device is connected to Wi-Fi. Use Logs in the dashboard after each update to confirm that the device boots correctly, connects to the network, and reports sensor or switch states as expected.

How to connect ESPHome devices to Home Assistant

ESPHome devices can connect to Home Assistant through the native ESPHome integration. This lets Home Assistant detect ESPHome sensors, switches, lights, and other entities after the device is flashed and connected to the same network.

In Home Assistant, go to Settings → Devices & services → Add integration, then search for ESPHome. Enter the device hostname or IP address when prompted. If the ESPHome API is enabled in the YAML file, Home Assistant can communicate with the device directly:

api:

A device named living-room-sensor usually uses a hostname like:

living-room-sensor.local

If Home Assistant cannot find the device automatically, use the device’s IP address instead. Keep the ESPHome device and Home Assistant server on the same network, especially when relying on local discovery.

What to do after setting up ESPHome

After ESPHome is running in Docker, keep your setup maintainable by giving each ESP device a clear YAML file, storing shared credentials in secrets.yaml, and backing up the /config folder regularly. These files contain the device definitions needed to rebuild firmware, restore configurations, or move ESPHome to another server.

For day-to-day management, use the ESPHome dashboard to validate YAML changes, install OTA updates, and review logs after each firmware change. If you want ESPHome to stay available without depending on a personal computer, deploy it on a VPS using Hostinger’s ESPHome Docker template and manage your ESP32 or ESP8266 devices from an always-on environment.

All of the tutorial content on this website is subject to Hostinger's rigorous editorial standards and values.

The author

Domantas Pocius

Domantas is a Content SEO Specialist who focuses on researching, writing, and optimizing content for organic growth. He explores content opportunities through keyword, market, and audience research to create search-driven content that matches user intent. Domantas also manages content workflows and timelines, ensuring SEO content initiatives are delivered accurately and on schedule. Follow him on LinkedIn.

More from Domantas Pocius