Skip to content
ESPHome - Smart Home Made Simple 2026.5.0

Web Server OTA Updates

The Web Server OTA platform allows you to upload new firmware binaries to your ESPHome devices directly through the web interface. This provides a user-friendly way to update devices without needing command-line tools or the ESPHome dashboard.

When enabled, an “OTA Update” section appears on the device’s web interface where you can select and upload a firmware file. This is particularly useful for devices that are deployed in the field or when you want to allow non-technical users to perform updates.

WARNING

Enabling OTA updates through the web interface without authentication allows anyone with network access to your device to upload new firmware. It is strongly recommended to enable authentication on the web server when using this feature.

# Example configuration entry
web_server:
  port: 80
  auth:
    username: !secret web_server_username
    password: !secret web_server_password


ota:
  - platform: web_server

Configuration variables

Section titled “Configuration variables”
  • id (Optional, ID): Manually specify the ID used for code generation.
  • All automations supported by Ota.

NOTE

This platform requires the Web Server component to be configured in your device.

Migration from Legacy Configuration

Section titled “Migration from Legacy Configuration”

Prior to ESPHome 2025.7.0, OTA functionality was built into the web_server component using the ota option. This has been moved to a separate platform for consistency with other OTA methods.

Old configuration:

web_server:
  port: 80
  ota: true  # or ota: false to disable

New configuration:

web_server:
  port: 80


ota:
  - platform: web_server  # Add this to enable web OTA

If you previously had ota: false in your web_server configuration, simply remove that line and don’t add the web_server OTA platform.

Example Configurations

Section titled “Example Configurations”

Basic setup with web server OTA:

# Basic configuration
web_server:
  port: 80


ota:
  - platform: web_server

Secure setup with authentication:

# Recommended: with authentication
web_server:
  port: 80
  auth:
    username: admin
    password: !secret web_password


ota:
  - platform: web_server

Using the Web Interface

Section titled “Using the Web Interface”
  1. Navigate to your device’s web interface at http://<device-ip>/ or http://<device-name>.local/
  2. If authentication is enabled, enter your username and password
  3. Scroll down to the “OTA Update” section
  4. Click “Choose File” and select your firmware file (firmware.bin )
  5. Click “Update” to start the upload
  6. Wait for the upload to complete - the device will automatically reboot with the new firmware

WARNING

  • Always use firmware.bin or firmware.ota.bin files for OTA updates, not firmware.factory.bin files
  • The web interface may become unresponsive during the update process - this is normal
  • Do not power off the device during an update

Using the Command Line

Section titled “Using the Command Line”

esphome upload and esphome run can upload firmware via the web_server OTA platform too. This is useful when:

  • The device only has platform: web_server configured under ota: (no native API OTA).
  • You no longer have the ESPHome OTA password but still know the web_server auth credentials.
  • The native API OTA port is blocked by a firewall while the configured web_server port (HTTP, default 80) is reachable.

When platform: web_server is the only OTA platform configured, the CLI selects it automatically. When both platform: esphome and platform: web_server are configured, the CLI prefers the native API OTA path by default because the native protocol uses challenge-response auth with hashed nonces (the password never crosses the wire), while the web_server path relies on HTTP Basic auth. Pass --ota-platform web_server to force the HTTP path anyway:

Terminal window
# Auto-select web_server OTA when it's the only platform configured:
esphome upload <config.yaml>


# Force the web_server OTA path with either upload or run:
esphome upload <config.yaml> --ota-platform web_server
esphome run <config.yaml> --ota-platform web_server

If a web_server auth block is configured, the CLI sends those credentials as an HTTP Basic Authorization header. The device challenges with WWW-Authenticate: Basic, so the credentials cross the network in cleartext. The --ota-platform web_server path does not use the ESPHome OTA password at all; it only uses the web_server auth credentials.

WARNING

HTTP Basic auth credentials are sent in cleartext on the local network, the same as the web UI upload flow. Treat the web_server auth username/password as a “local-network-only” secret. If you have a choice, prefer platform: esphome for CLI uploads since it never sends the password over the wire.

See Also

Section titled “See Also”