{"id":133798,"date":"2026-05-25T04:02:52","date_gmt":"2026-05-25T04:02:52","guid":{"rendered":"\/in\/tutorials\/how-to-install-esphome-docker"},"modified":"2026-05-25T04:02:52","modified_gmt":"2026-05-25T04:02:52","slug":"how-to-install-esphome-docker","status":"publish","type":"post","link":"\/in\/tutorials\/how-to-install-esphome-docker","title":{"rendered":"How to install ESPHome with Docker to manage ESP32 and ESP8266 devices"},"content":{"rendered":"<p>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.<\/p><p>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&rsquo;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.<\/p><h2 class=\"wp-block-heading\" id=\"h-what-do-you-need-before-installing-esphome-with-docker\">What do you need before installing ESPHome with Docker?<\/h2><p>Before installing ESPHome with Docker, <a href=\"\/in\/tutorials\/how-to-install-docker-on-ubuntu\">prepare a server with Docker<\/a>, 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.<\/p><p>You need:<\/p><ol class=\"wp-block-list\">\n<li><strong>A server or local machine with Docker installed<\/strong> &ndash; ESPHome can run on a <a href=\"\/in\/vps\">VPS<\/a>, 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.<\/li>\n\n\n\n<li><strong>Docker Compose<\/strong> &ndash; <a href=\"\/in\/tutorials\/what-is-docker-compose\">Docker Compose<\/a> is recommended for long-term ESPHome management because it keeps the container configuration in one reusable file and restarts ESPHome after server reboots.<\/li>\n\n\n\n<li><strong>An ESP32 or ESP8266 device<\/strong> &ndash; 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.<\/li>\n\n\n\n<li><strong>A USB data cable<\/strong> &ndash; The first firmware installation usually requires connecting the ESP device to the machine running ESPHome. Use a data-transfer cable, not a charging cable.<\/li>\n\n\n\n<li><strong>Wi-Fi network credentials<\/strong> &ndash; ESPHome needs your Wi-Fi SSID and password so the ESP device can connect to the network after flashing.<\/li>\n\n\n\n<li><strong>A persistent ESPHome configuration folder<\/strong> &ndash; This folder stores YAML files, secrets, build files, and device settings. In Docker, it is usually mounted to the container as \/config.<\/li>\n\n\n\n<li><strong>Access to port 6052 &ndash; ESPHome uses it<\/strong> for the dashboard. Make sure this port is available and allowed by your server firewall.<\/li>\n\n\n\n<li><strong>Optional Home Assistant installation<\/strong> &ndash; 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.<\/li>\n\n\n\n<li><strong>Optional Hostinger VPS with the ESPHome Docker template<\/strong> &ndash; <a href=\"\/in\/vps\/docker\">Hostinger&rsquo;s Docker template<\/a> is useful if you want to deploy ESPHome on an always-on VPS without manually creating the Docker setup.<\/li>\n<\/ol><p>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.<\/p><h2 class=\"wp-block-heading\" id=\"h-how-to-install-esphome-with-docker\">How to install ESPHome with Docker<\/h2><p>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.<\/p><h3 class=\"wp-block-heading\">1. Create an ESPHome configuration directory<\/h3><p>First, create a dedicated directory for ESPHome. This folder stores your YAML configuration files, device secrets, firmware build files, and dashboard data.<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">mkdir -p ~\/esphome\/config\ncd ~\/esphome<\/pre><p>ESPHome stores its project files inside the container&rsquo;s \/config directory. Mapping ~\/esphome\/config to \/config keeps your device configurations available after the container restarts or updates.<\/p><h3 class=\"wp-block-heading\">2. Run ESPHome with Docker CLI<\/h3><p>Use the official ESPHome Docker image to start the dashboard:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">docker run --rm --net=host\n-v \"$PWD\/config\":\/config\n-it ghcr.io\/esphome\/esphome<\/pre><p>This command starts ESPHome in the foreground. Here is what each option does:<\/p><figure tabindex=\"0\" class=\"wp-block-table\"><table><tbody><tr><td colspan=\"1\" rowspan=\"1\"><p><strong>Option<\/strong><\/p><\/td><td colspan=\"1\" rowspan=\"1\"><p><strong>Purpose<\/strong><\/p><\/td><\/tr><tr><td colspan=\"1\" rowspan=\"1\"><p><span>&ndash;rm<\/span><\/p><\/td><td colspan=\"1\" rowspan=\"1\"><p><span>Removes the container after it stops.<\/span><\/p><\/td><\/tr><tr><td colspan=\"1\" rowspan=\"1\"><p><span>&ndash;net=host<\/span><\/p><\/td><td colspan=\"1\" rowspan=\"1\"><p><span>Lets ESPHome communicate with devices on the local network.<\/span><\/p><\/td><\/tr><tr><td colspan=\"1\" rowspan=\"1\"><p><span>-v &ldquo;$PWD\/config&rdquo;:\/config<\/span><\/p><\/td><td colspan=\"1\" rowspan=\"1\"><p><span>Saves ESPHome files in your local <\/span><span>config<\/span><span>&nbsp;folder.<\/span><\/p><\/td><\/tr><tr><td colspan=\"1\" rowspan=\"1\"><p><span>-it<\/span><\/p><\/td><td colspan=\"1\" rowspan=\"1\"><p><span>Runs the container interactively.<\/span><\/p><\/td><\/tr><tr><td colspan=\"1\" rowspan=\"1\"><p><span>ghcr.io\/esphome\/esphome<\/span><\/p><\/td><td colspan=\"1\" rowspan=\"1\"><p><span>Uses the official ESPHome container image.<\/span><\/p><\/td><\/tr><\/tbody><\/table><\/figure><p>This method works well for testing ESPHome or creating your first device configuration. For a long-term setup, use Docker Compose instead.<\/p><h3 class=\"wp-block-heading\">3. Install ESPHome with Docker Compose<\/h3><p>Docker Compose keeps ESPHome running as a persistent service. Create a docker-compose.yml file inside the ~\/esphome directory:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">nano docker-compose.yml<\/pre><p>Add the following configuration:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">services:\nesphome:\ncontainer_name: esphome\nimage: ghcr.io\/esphome\/esphome\nvolumes:\n- .\/config:\/config\n- \/etc\/localtime:\/etc\/localtime:ro\nrestart: always\nprivileged: true\nnetwork_mode: host<\/pre><p>Save the file and start ESPHome:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">docker compose up -d<\/pre><p>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.<\/p><p>To check whether the container is running, use:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">docker ps<\/pre><p>You should see a container named esphome in the output.<\/p><h3 class=\"wp-block-heading\">4. Open the ESPHome dashboard<\/h3><p>After the container starts, open the ESPHome dashboard in your browser:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">http:\/\/SERVER-IP:6052<\/pre><p>Replace SERVER-IP with your server&rsquo;s IP address. If you installed ESPHome on your local machine, use:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">http:\/\/localhost:6052<\/pre><p>The dashboard is where you create ESPHome YAML files, compile firmware, install updates, and view device logs.<\/p><h3 class=\"wp-block-heading\">5. Check ESPHome container logs<\/h3><p>If the dashboard does not load, check the container logs:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">docker logs esphome<\/pre><p>For a live log view, run:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">docker logs -f esphome<\/pre><p>The logs help identify startup errors, permission issues, missing volumes, or network problems.<\/p><h3 class=\"wp-block-heading\">6. Update ESPHome later<\/h3><p>To update ESPHome with Docker Compose, pull the latest image and recreate the container:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">docker compose pull\ndocker compose up -d<\/pre><p>Your YAML files remain available because they are stored in the mapped .\/config directory, not inside the container itself.<\/p><h3 class=\"wp-block-heading\">7. Stop or restart ESPHome<\/h3><p>Use these commands to manage the ESPHome container:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">docker compose restart<\/pre><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">docker compose stop<\/pre><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">docker compose up -d<\/pre><p>Restart ESPHome after changing Docker settings, updating the image, or troubleshooting dashboard access.<\/p><h2 class=\"wp-block-heading\" id=\"h-how-to-deploy-esphome-faster-with-hostingers-docker-template\">How to deploy ESPHome faster with Hostinger&rsquo;s Docker template<\/h2><p>Hostinger&rsquo;s <a href=\"\/in\/vps\/docker\/esphome\">ESPHome Docker template<\/a> 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.<\/p><p>Follow these steps to deploy ESPHome with Hostinger&rsquo;s Docker template:<\/p><ol class=\"wp-block-list\">\n<li>Log in to hPanel.<\/li>\n\n\n\n<li>Go to <strong>VPS<\/strong> and choose your server.<\/li>\n\n\n\n<li>Open <strong>OS &amp; Panel<\/strong>.<\/li>\n\n\n\n<li>Select <strong>Docker<\/strong> as the VPS template category.<\/li>\n\n\n\n<li>Choose the <strong>ESPHome<\/strong> Docker template.<\/li>\n\n\n\n<li>Reinstall or deploy the template on your VPS.<\/li>\n\n\n\n<li>Wait until the installation finishes.<\/li>\n\n\n\n<li>Open the ESPHome dashboard using your VPS IP address and port 6052:<\/li>\n<\/ol><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">http:\/\/SERVER-IP:6052<\/pre><p>Replace SERVER-IP with your VPS IP address.<\/p><p>Using Hostinger&rsquo;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.<\/p><p>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.<\/p><p>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.<\/p><h2 class=\"wp-block-heading\" id=\"h-how-to-create-your-first-esphome-device-configuration\">How to create your first ESPHome device configuration<\/h2><p>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.<\/p><h3 class=\"wp-block-heading\">1. Open the ESPHome dashboard<\/h3><p>Open your ESPHome dashboard in a browser:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">http:\/\/SERVER-IP:6052<\/pre><p>Replace SERVER-IP with your VPS or server IP address. If ESPHome runs on your local machine, use:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">http:\/\/localhost:6052<\/pre><p>The dashboard lets you create, edit, validate, compile, and install ESPHome configurations.<\/p><h3 class=\"wp-block-heading\">2. Create a new device<\/h3><p>In the ESPHome dashboard, click <strong>New Device<\/strong>. Enter a clear device name that describes the device location or function, such as living-room-sensor, bedroom-plug, or garage-door-sensor.<\/p><p>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.<\/p><h3 class=\"wp-block-heading\">3. Select the ESP board type<\/h3><p>Choose the board that matches your physical device. ESPHome uses this board setting to compile firmware with the correct platform settings and pin layout.<\/p><p>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.<\/p><h3 class=\"wp-block-heading\">4. Enter Wi-Fi credentials<\/h3><p>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.<\/p><p>A basic Wi-Fi configuration looks like this:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">wifi:\nssid: \"Your_WiFi_Name\"\npassword: \"Your_WiFi_Password\"<\/pre><p>For better configuration management, store credentials in secrets.yaml:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">wifi:\nssid: !secret wifi_ssid\npassword: !secret wifi_password<\/pre><p>Then add the actual values to secrets.yaml:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">wifi_ssid: \"Your_WiFi_Name\"\nwifi_password: \"Your_WiFi_Password\"<\/pre><p>This keeps Wi-Fi credentials separate from each device file.<\/p><h3 class=\"wp-block-heading\">5. Review the generated YAML file<\/h3><p>After you complete the setup wizard, ESPHome creates a YAML file for the device. A basic ESP32 configuration may look like this:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">esphome:\nname: living-room-sensor\nesp32:\nboard: esp32dev\nframework:\ntype: arduino\nlogger:\napi:\nota:\nwifi:\nssid: !secret wifi_ssid\npassword: !secret wifi_password<\/pre><p>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.<\/p><p>For an ESP8266 board, replace the ESP32 section with:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">esp8266:\nboard: nodemcuv2<\/pre><p>Use the platform section that matches your device. A mismatched board setting can cause failed builds, incorrect GPIO behavior, or unstable firmware.<\/p><h3 class=\"wp-block-heading\">6. Add a basic component<\/h3><p>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:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">switch:\nplatform: gpio\nname: \"Living Room Lamp\"\npin: GPIO5<\/pre><p>This tells ESPHome to control the GPIO5 pin as a switch named <strong>Living Room Lamp<\/strong>. After the device is added to Home Assistant, the switch appears as a controllable entity.<\/p><p>For a simple status sensor, add a Wi-Fi signal sensor:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">sensor:\nplatform: wifi_signal\nname: \"Living Room Sensor WiFi Signal\"\nupdate_interval: 60s<\/pre><p>This sensor reports the device&rsquo;s Wi-Fi signal strength every 60 seconds, which helps confirm whether the ESP device has a stable network connection.<\/p><h3 class=\"wp-block-heading\">7. Validate the configuration<\/h3><p>Before compiling firmware, validate the YAML file from the ESPHome dashboard. You can also validate it from the command line:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">docker run --rm -v \"$PWD\/config\":\/config -it ghcr.io\/esphome\/esphome config living-room-sensor.yaml<\/pre><p>Replace living-room-sensor.yaml with your configuration file name.<\/p><p>Validation checks the YAML syntax, board settings, component configuration, and required fields. Fix any errors before compiling or flashing the firmware.<\/p><h3 class=\"wp-block-heading\">8. Save the configuration for future device management<\/h3><p>Each ESPHome device should have its own YAML file in the \/config directory:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">config\/\nliving-room-sensor.yaml\nbedroom-plug.yaml\ngarage-door-sensor.yaml\nkitchen-light-switch.yaml\nsecrets.yaml<\/pre><p>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.<\/p><h2 class=\"wp-block-heading\" id=\"h-how-to-flash-esp32-and-esp8266-devices-with-esphome\">How to flash ESP32 and ESP8266 devices with ESPHome<\/h2><p>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.<\/p><h3 class=\"wp-block-heading\">1. Connect the ESP device to your server<\/h3><p>Connect the ESP32 or ESP8266 board to the machine running Docker. Use a USB cable that supports data transfer, not a charge-only cable.<\/p><p>Then check which serial port the device uses:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">ls \/dev\/ttyUSB*<\/pre><p>If that command returns no device, try:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">ls \/dev\/ttyACM*<\/pre><p>Most ESP boards appear as \/dev\/ttyUSB0 or \/dev\/ttyACM0. Use the detected path in the flashing command.<\/p><h3 class=\"wp-block-heading\">2. Flash the device from the ESPHome dashboard<\/h3><p>Open the ESPHome dashboard:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">http:\/\/SERVER-IP:6052<\/pre><p>Find the device configuration you created earlier, then click <strong>Install<\/strong>. ESPHome will ask how you want to install the firmware.<\/p><p>Choose <strong>Plug into the computer running ESPHome Dashboard<\/strong> 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.<\/p><p>If the dashboard does not detect the board, use the command-line method instead.<\/p><h3 class=\"wp-block-heading\">3. Flash the device with Docker CLI<\/h3><p>Run the ESPHome container with USB device access:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">docker run --rm --privileged\n-v \"$PWD\/config\":\/config\n--device=\/dev\/ttyUSB0\n-it ghcr.io\/esphome\/esphome run living-room-sensor.yaml<\/pre><p>Replace \/dev\/ttyUSB0 with your detected serial device. Replace living-room-sensor.yaml with your ESPHome configuration file.<\/p><p>This command validates the YAML file, compiles the firmware, uploads it to the ESP board, and opens the device logs after installation. The &ndash;privileged option gives the container the permissions needed to access the USB device.<\/p><h3 class=\"wp-block-heading\">4. Flash the device with Docker Compose<\/h3><p>If you installed ESPHome with Docker Compose, add the USB device to your docker-compose.yml file:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">services:\nesphome:\ncontainer_name: esphome\nimage: ghcr.io\/esphome\/esphome\nvolumes:\n- .\/config:\/config\n- \/etc\/localtime:\/etc\/localtime:ro\nrestart: always\nprivileged: true\ndevices:\n- \/dev\/ttyUSB0:\/dev\/ttyUSB0\nnetwork_mode: host<\/pre><p>Restart the container after saving the file:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">docker compose up -d<\/pre><p>Then return to the ESPHome dashboard and install the firmware again. ESPHome should now be able to access the USB-connected board.<\/p><h3 class=\"wp-block-heading\">5. Put the board into bootloader mode if flashing fails<\/h3><p>Some ESP32 and ESP8266 boards enter flashing mode automatically. Others require manual bootloader mode.<\/p><p>Press and hold the <strong>BOOT<\/strong> or <strong>FLASH<\/strong> 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.<\/p><h3 class=\"wp-block-heading\">6. Use OTA updates after the first flash<\/h3><p>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.<\/p><p>To update the device later, edit the YAML file, click <strong>Install<\/strong>, and choose <strong>Wirelessly<\/strong>. ESPHome will compile the new firmware and send it to the device over the network.<\/p><p>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.<\/p><h2 class=\"wp-block-heading\" id=\"h-how-to-manage-esp-devices-after-installation\">How to manage ESP devices after installation<\/h2><p>After installation, ESPHome manages ESP32 and ESP8266 devices through the dashboard and each device&rsquo;s YAML configuration file. Use the dashboard to edit configurations, validate changes, compile firmware, install updates, and check device logs.<\/p><p>Each ESP device should have its own YAML file in the \/config directory:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">config\/\nliving-room-sensor.yaml\nbedroom-plug.yaml\ngarage-door-relay.yaml\nsecrets.yaml<\/pre><p>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.<\/p><p>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:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">switch:\nplatform: gpio\nname: \"Garage Door Relay\"\npin: GPIO5<\/pre><p>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 <strong>Logs<\/strong> 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.<\/p><h2 class=\"wp-block-heading\" id=\"h-how-to-connect-esphome-devices-to-home-assistant\">How to connect ESPHome devices to Home Assistant<\/h2><p>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.<\/p><p>In Home Assistant, go to <strong>Settings &rarr; Devices &amp; services &rarr; Add integration<\/strong>, then search for <strong>ESPHome<\/strong>. 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:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">api:<\/pre><p>A device named living-room-sensor usually uses a hostname like:<\/p><pre class=\"EnlighterJSRAW\" data-enlighter-language=\"generic\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">living-room-sensor.local<\/pre><p>If Home Assistant cannot find the device automatically, use the device&rsquo;s IP address instead. Keep the ESPHome device and Home Assistant server on the same network, especially when relying on local discovery.<\/p><h2 class=\"wp-block-heading\" id=\"h-what-to-do-after-setting-up-esphome\">What to do after setting up ESPHome<\/h2><p>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.<\/p><p>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&rsquo;s ESPHome Docker template and manage your ESP32 or ESP8266 devices from an always-on environment.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>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 [&#8230;]<\/p>\n<p><a class=\"btn btn-secondary understrap-read-more-link\" href=\"\/in\/tutorials\/how-to-install-esphome-docker\">Read More&#8230;<\/a><\/p>\n","protected":false},"author":342,"featured_media":133799,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"How to install ESPHome with Docker","rank_math_description":"Learn how to install ESPHome with Docker, create ESP32 and ESP8266 configurations, flash devices, and manage firmware updates from the dashboard.","rank_math_focus_keyword":"esphome docker","footnotes":""},"categories":[22640],"tags":[],"class_list":["post-133798","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-vps"],"hreflangs":[{"locale":"en-US","link":"https:\/\/www.hostinger.com\/tutorials\/how-to-install-esphome-docker","default":1},{"locale":"en-PH","link":"https:\/\/www.hostinger.com\/ph\/tutorials\/how-to-install-esphome-docker","default":0},{"locale":"en-MY","link":"https:\/\/www.hostinger.com\/my\/tutorials\/how-to-install-esphome-docker","default":0},{"locale":"en-UK","link":"https:\/\/www.hostinger.com\/uk\/tutorials\/how-to-install-esphome-docker","default":0},{"locale":"en-IN","link":"https:\/\/www.hostinger.com\/in\/tutorials\/how-to-install-esphome-docker","default":0},{"locale":"en-CA","link":"https:\/\/www.hostinger.com\/ca\/tutorials\/how-to-install-esphome-docker","default":0},{"locale":"en-AU","link":"https:\/\/www.hostinger.com\/au\/tutorials\/how-to-install-esphome-docker","default":0},{"locale":"en-NG","link":"https:\/\/www.hostinger.com\/ng\/tutorials\/how-to-install-esphome-docker","default":0}],"_links":{"self":[{"href":"https:\/\/www.hostinger.com\/in\/tutorials\/wp-json\/wp\/v2\/posts\/133798","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.hostinger.com\/in\/tutorials\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.hostinger.com\/in\/tutorials\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.hostinger.com\/in\/tutorials\/wp-json\/wp\/v2\/users\/342"}],"replies":[{"embeddable":true,"href":"https:\/\/www.hostinger.com\/in\/tutorials\/wp-json\/wp\/v2\/comments?post=133798"}],"version-history":[{"count":0,"href":"https:\/\/www.hostinger.com\/in\/tutorials\/wp-json\/wp\/v2\/posts\/133798\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.hostinger.com\/in\/tutorials\/wp-json\/wp\/v2\/media\/133799"}],"wp:attachment":[{"href":"https:\/\/www.hostinger.com\/in\/tutorials\/wp-json\/wp\/v2\/media?parent=133798"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.hostinger.com\/in\/tutorials\/wp-json\/wp\/v2\/categories?post=133798"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.hostinger.com\/in\/tutorials\/wp-json\/wp\/v2\/tags?post=133798"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}