ESPHome OTA Updates: Secure Setup and Troubleshooting (2026)

Albert BarnosellEditor and publisher of Tecnoyfoto

Updated August 3, 2026. I reviewed this entire guide for the changes introduced in ESPHome 2024.6, 2025.7, and 2026.1, and removed passwords written directly in the examples.

ESPHome OTA updates let you install new firmware over the network without reconnecting the device over USB. For most Home Assistant installations, the recommended choice is ESPHome’s native OTA platform, protected by a unique password stored in secrets.yaml.

The syntax changed significantly in June 2024. The old standalone ota: component became a list of platforms. Web-based firmware uploads later became a separate explicit platform as well. This guide explains which method to choose, how to migrate without losing access, and what to check when an update fails.

What OTA means—and what it cannot do

OTA means Over the Air. ESPHome compiles firmware for a specific board, transfers it over Wi-Fi or Ethernet, and the device writes it to an update partition. After a successful installation, the node reboots into the new firmware.

• OTA does not replace the first USB installation on a new board.
• It cannot recover every hardware, partition, or network failure.
• It does not make an ESP device safe to expose directly to the internet.
• The API encryption key and OTA password are separate credentials.

Always keep the YAML, its secrets, and a reasonable way to reach the hardware. OTA is convenient, but USB remains the most dependable recovery path.

Three ESPHome changes behind most outdated OTA examples

The official ESPHome OTA documentation lists the current platforms and options. Do not paste an OTA block from 2023 or early 2024 without migrating it.

Recommended secure ESPHome OTA configuration

This is a secure minimal example for an ESP32 connected to Home Assistant. Replace the board ID and let ESPHome generate the API key:

esphome:
  name: living-room-sensor
  friendly_name: Living Room Sensor

esp32:
  board: esp32dev
  framework:
    type: esp-idf

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

logger:
  level: INFO

api:
  encryption:
    key: !secret living_room_sensor_api_key

ota:
  - platform: esphome
    password: !secret living_room_sensor_ota_password

The dash before platform matters because ota contains a list. The intermediate-looking form ota: platform: esphome without a list is not valid current syntax either.

Credentials in secrets.yaml

wifi_ssid: "Your network name"
wifi_password: "Your Wi-Fi password"
living_room_sensor_api_key: "BASE64_KEY_GENERATED_BY_ESPHOME"
living_room_sensor_ota_password: "a-long-unique-ota-password"
living_room_sensor_web_username: "admin-living-room-sensor"
living_room_sensor_web_password: "another-long-unique-password"

secrets.yaml prevents credentials from appearing in the shared YAML, but it does not encrypt the file on your system. Never commit or publish it. ESPHome’s Security Best Practices recommend a different API key, OTA password, and web credential set for every node. Wi-Fi credentials are the common exception.

For larger installations, our ESPHome substitutions and packages guide explains how to reuse structure without duplicating secrets.

ESPHome OTA methods compared

A normal Home Assistant installation does not need every method. Native ESPHome OTA is usually enough and exposes less functionality.

Current web_server OTA configuration

Since ESPHome 2025.7, enabling web_server no longer adds firmware uploads by itself. You must configure the OTA platform explicitly:

web_server:
  port: 80
  version: 3
  auth:
    username: !secret living_room_sensor_web_username
    password: !secret living_room_sensor_web_password
    type: basic

ota:
  - platform: esphome
    password: !secret living_room_sensor_ota_password
  - platform: web_server

Basic authentication blocks anonymous access, but it does not encrypt credentials over HTTP. Use this only on a trusted home network or isolated IoT VLAN, and never forward the port from your router. If browser uploads are unnecessary, remove the web_server OTA platform and keep native OTA only.

When both platforms exist, the CLI prefers native OTA. Current ESPHome lets you select a path explicitly:

esphome upload living-room-sensor.yaml --ota-platform web_server
esphome run living-room-sensor.yaml --ota-platform esphome

For manual browser uploads, choose firmware.ota.bin—also labeled OTA format—not firmware.factory.bin. The official Web Server OTA documentation explains the current workflow.

HTTP Request OTA for advanced deployments

With platform: http_request, the device acts as a client. It downloads a firmware.ota.bin file from a server and installs it through an automation. This can work well for standalone or MQTT-only devices, including nodes behind a firewall.

http_request:
  verify_ssl: true

ota:
  - platform: http_request

This only enables the backend. You still need an installation action, URL, integrity verification, and secure release process. Do not disable TLS verification simply to silence an error. Read the HTTP Request OTA reference before using it in production.

Migrating old OTA syntax

If your configuration still contains this format:

# Pre-2024.6 syntax: do not use in new configurations
ota:
  password: !secret ota_password

replace it with:

ota:
  - platform: esphome
    password: !secret ota_password

1. Update ESPHome Device Builder or your CLI first.
2. Back up the YAML and secrets.yaml.
3. Change only the OTA block, then validate the configuration.
4. Update one test device before rolling the change out everywhere.
5. Confirm that the node reconnects to Home Assistant with the same name and entities.

The original Tecnoyfoto video documents the first 2024.6 migration. Web Server OTA separation and SHA-256 compatibility arrived later, so use the code in this article as the final reference.

OTA compatibility since ESPHome 2026.1

ESPHome 2026.1 removed MD5 OTA authentication and requires SHA-256. If a device already runs 2026.1 or later, a Dashboard or CLI older than 2025.10 cannot update it with password authentication. Update every system you use to install firmware before updating the devices themselves.

Downgrades also require planning. To move from 2026.1 or later to a release older than 2025.10, the documented path goes through ESPHome 2025.12.x first. Jumping directly to a much older release may leave USB as the only recovery option.

Updating from Device Builder or the CLI

1. Confirm the node is online and has a reasonable Wi-Fi signal.
2. Validate and compile the YAML before uploading.
3. Verify the device name and address so you do not update the wrong node.
4. Start the installation and do not remove power.
5. Wait for the reboot, check the logs, and confirm the node returns online.

esphome config living-room-sensor.yaml
esphome compile living-room-sensor.yaml
esphome upload living-room-sensor.yaml

esphome run combines compilation, upload, and logs. For a major change, separating validation, compilation, and upload makes it easier to identify the failing stage.

Common ESPHome OTA errors and fixes

Using use_address after an IP or name change

If ESPHome tries the wrong destination after a hostname or address change, temporarily point it at the address the node still uses:

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

Remove use_address after a successful update. A DHCP reservation can provide predictable addresses without hard-coding an IP, gateway, and subnet into every node.

Safe Mode: ESPHome’s OTA recovery path

OTA automatically enables Safe Mode support. After repeated boot failures, ESPHome can start only networking, serial logging, and the configured OTA platforms while leaving sensors and actuators disabled. This gives you an opportunity to upload a fix.

Do not disable Safe Mode on hard-to-reach devices without a specific technical reason. It is still not an absolute guarantee: insufficient flash space, a broken network configuration, or an incompatible partition layout may require physical access.

Pre-update security checklist

• Current ESPHome Device Builder and CLI.
• Backups of the YAML and secrets.yaml.
• A unique OTA password stored outside the shared configuration.
• Native API encryption with a separate key.
• web_server disabled when unnecessary or authenticated when required.
• No ESPHome ports exposed directly to the internet.
• One test node updated before a fleet-wide rollout.
• A USB recovery path available.

If you are preparing a node from scratch, our complete ESP32 and ESPHome guide includes a secure base configuration and restricted GPIO guidance.

ESPHome OTA FAQ

Does ESPHome OTA require a static IP?

No. ESPHome can find a node through mDNS or its DHCP address. A DHCP reservation can make troubleshooting easier, but a manually configured IP is not required.

Can I use the API key as the OTA password?

No. The API key encrypts communication with Home Assistant. Native OTA uses its own password, and both credentials should be unique.

Can I update ESPHome from outside my home?

Do not publish OTA or web_server ports to the internet. If remote maintenance is essential, connect to your home network through a properly configured VPN first.

Which firmware file should I upload in the browser?

Use firmware.ota.bin or the file downloaded in OTA format. The factory image is intended for first installation and should not be used for this path.

Conclusion

The right setup for most users is simple: platform: esphome, a unique password in secrets.yaml, current tools, and no internet-exposed ports. Add Web Server OTA or HTTP Request only when you have a real need and understand the security model.

Technical sources: official documentation for Over-the-Air Updates, ESPHome OTA, Web Server OTA, HTTP Request OTA, and Safe Mode.

Continue reading

Next related guide · 6 min read

ESPHome Substitutions and Packages: Practical YAML Guide

Updated August 2, 2026 for the current ESPHome syntax. Once you have several ESPHome devices, copying the same Wi-Fi, API, OTA, and diagnostic sensors…

Continue with this article↓