ESPHome can now update a finished device over the network with just a firmware file and an IP address

A pull request merged into ESPHome's development branch on 28 October 2026 (01:48 Polish time) lets esphome upload send a prebuilt firmware image to a device without a YAML configuration. The change is by Nate Clark and was reviewed by J. Nick Koston (bdraco). It targets a group ESPHome rarely served well from the command line: owners of finished products that run ESPHome but whose configuration belongs to the manufacturer.

The problem it solves

Many devices with ESPHome are sold ready to use. The maker writes and maintains the configuration and publishes a compiled image for each release. The customer never had the YAML file. Until now, esphome upload refused to run without one, even when --file and --device were both given. The workaround was a stub configuration that existed only to pass validation. It had to match the chip family, include a network component and so on, which the pull request describes as "hard to explain to customers and easy to get wrong".

How it works

The configuration argument is now optional. Without it, --file and at least one --device are required, and the image goes straight to the over-the-air (OTA) uploader. Nothing is read, validated or compiled. Examples from the pull request:

esphome upload --file firmware.bin --device 192.168.1.50
ESPHOME_OTA_PASSWORD=secret esphome upload --file firmware.bin --device 192.168.1.50
ESPHOME_OTA_KEY=<base64 key> esphome upload --file firmware.bin --device 192.168.1.50

The OTA port is taken from the image header, which identifies the platform it was built for. ESP32 and ESP8266 images, BK72xx, RTL87xx and LN882x UF2 files, and RP2040 and RP2350 images are recognised. The author says he checked the detection against 179 of his own builds plus the official RP2040/RP2350 blink example. If the header does not name a platform, for example an original ESP32 factory image that starts with padding, the upload is refused and you must give --ota-port. No port is guessed.

New --ota-port and --ota-password options are added. The password can also come from an ESPHOME_OTA_PASSWORD environment variable, which is removed from the environment after reading so it stays out of the shell history and process list. The encryption key still comes from ESPHOME_OTA_KEY or --prompt-ota-key, and it is checked before connecting, so a bad key never falls back to an unencrypted upload. A missing or unreadable file fails before the device is contacted.

Limits

This path only sends an existing image over the network. Serial flashing, uploads over MQTT, the BOOTSEL mode on the RP2040 and updates through a device's web_server OTA platform still need a configuration and are refused with a clear error. When a configuration is given, the new port and password options are rejected instead of silently ignored, because the configuration's settings apply. Uploads with a configuration behave exactly as before.

The change is in the dev branch and carries an "awaiting docs approval" label. No release has been named, but changes merged now normally ship in the next monthly version, 2026.11.