ESPHome 2026.7.0: Every Breaking Change, Ranked by Pain

This post may contain affiliate links. As an Amazon Associate we earn from qualifying purchases. Disclosure.

ESPHome 2026.7.0 shipped in July 2026 carrying 217 merged pull requests from more than thirty contributors. Most of them you'll never notice. Half a dozen will stop your build cold, and one of them makes every Zigbee device in your house forget who it is.

I run about 40 ESPHome nodes, mostly ESP8266 d1_minis with a few ESP32 boards, so I read these changelogs the way other people read weather warnings. This one earns the attention. If you want the ground floor on what ESPHome is and how the YAML-to-firmware workflow fits together, start with the full ESPHome and Home Assistant guide and come back here. This page is only about what changes when you upgrade.

What follows is every breaking change in the release, ranked by pain rather than by the order the changelog lists them. Because the changelog is organised by component, and your evening is not.

The Zigbee One Is Worst, and There's No Way Around It

ESPHome 2026.7.0 moves to esp-zigbee-sdk 2.0.2. The consequence is blunt: every Zigbee device requires a re-join, a re-interview, and reconfiguration.

Not some. Every one.

There's no migration path that dodges this, no compatibility shim, no "it'll sort itself out after a reboot". Do you remember where you mounted all of them? Neither do I, and that's the actual cost of this change. If you have twelve Zigbee sensors scattered around the house, you're re-pairing twelve sensors, including the one behind the washing machine you swore you'd never touch again. The enabled and coordinator options under Zigbee reporting: are gone as well, so any config carrying them fails validation before you even get to the re-pairing.

My advice? Don't start this at eleven at night. Do it on a Saturday morning when you can walk the house with a laptop, and write down where every device actually lives before you unpair anything. The re-interview step is the slow part, and a device that was borderline on signal before will be borderline again.

There's an upside buried in the same change: Zigbee endpoint merging arrives with the 2.0.2 SDK. Multi-endpoint devices that used to sprawl across your entity list get tidier. That doesn't make the re-join fun, but it's something.

Modbus Split in Two

The Modbus component is now ModbusClientHub and ModbusServerHub. Client components move to ModbusClientDevice. The role enum that used to sort this out is retired entirely.

Two timing defaults changed, and these will bite quietly rather than loudly:

• send_wait_time went from 250ms to 2000ms
• turnaround_time went from 100ms to 600ms

Read those numbers again. That's an eightfold and a sixfold increase. Would you spot that from the logs? You wouldn't, because nothing errors. If you tuned a Modbus poll loop to feel responsive, it just got slower and stayed silent about it. Your energy meter will still report, only later, and you'll spend an hour blaming the WiFi.

The disable_crc option under modbus: is removed. The server-side send_wait_time and turnaround_time keys are gone too.

The rewritten parser and heap-free send path underneath are genuinely good engineering, and on a busy Modbus bus the new defaults are more conservative for a reason. The migration is still a chore, and if you have a working setup you'll want to re-tune those two values back down deliberately rather than discovering them by accident.

The rp2040 Rename

The rp2040: platform key becomes rp2:, reflecting that it now covers both the RP2040 and the RP2350. New variants are rp2_2040 and rp2_2350.

This one's handled gracefully. The old rp2040: key works as a deprecated alias all the way through 2027.7.0, which gives you a full year of runway. Rename it when you're touching the file anyway. There's no rush and no reason to make a project of it.

Your ESP32 Build Just Changed Toolchain

Configurations without an explicit toolchain: key now compile with native ESP-IDF instead of PlatformIO. Same story for nRF52, which defaults to the native nRF Connect SDK 2.9.2.

If your build breaks in a way that makes no sense, check this first. The escape hatch is one line:

esp32:
  toolchain: platformio

Is switching the default toolchain in a point release aggressive? A bit, yes. But ccache is on by default for ESP-IDF now, and there's a shared machine-global toolchain cache, so the rebuild cost drops sharply after the first one. The first compile after upgrading will feel slow. The second won't.

The Quiet Ones That Still Fail Validation

These won't make headlines and they'll still stop your install:

• Packages include: packages: !include mypackage.yaml now needs wrapping as packages: [!include mypackage.yaml]
• Image components: the top-level image:, animation: and online_image: keys are deprecated through 2027.1.0, replaced by platform: file, platform: animation and platform: online_image
• Web server: version: 1 is deprecated with a 2027.1.0 deadline, object ID addressing is replaced by entity name, cross-origin callers need adding to web_server: allowed_origins:, and anything relying on the old default needs enable_private_network_access: true
• HUB75 displays: FOUR_SCAN_16PX_HIGH becomes SCAN_1_4_16PX_HIGH, FOUR_SCAN_32PX_HIGH becomes SCAN_1_8_32PX_HIGH, and FOUR_SCAN_64PX_HIGH becomes SCAN_1_8_64PX_HIGH
• LibreTiny LN882H: the generic-ln882hki board becomes generic-ln882h or generic-ln882h-tuya, and the wb02a pin mapping changed for D1, D7, D8, D9 plus the default I2C aliases
• Light brightness: setting brightness to 0 now preserves the value instead of clamping it to 1.0

That last one is subtle enough to be dangerous. It won't fail validation, it won't error, and it won't appear in your logs. If an automation of yours sets brightness to zero expecting the old clamp, the behaviour silently flipped and your lamp now does something different at midnight. This is the kind of change that costs a weekend precisely because it looks like nothing.

The web server changes deserve a second look too, especially the cross-origin ones. If you embed ESPHome device pages in a dashboard served from another host, that dashboard is the cross-origin caller, and it stops working until you list it.

The Security Work Is the Real Story

Underneath the breakage, 2026.7.0 lands the first coordinated wave of EN18031 compliance work, and it's more interesting than any of the renames.

NVS encryption is opt-in, using the HMAC peripheral on the ESP32 S2, S3, C3, C5, C6, H2 and P4. Keys derive at runtime from an eFuse-burned HMAC key. That eFuse burn is irreversible. Think carefully before you flash it, because there's no undo, and a board you've burned is a board that behaves that way forever.

OTA downgrade protection compares the staged image version, taken from project: version:, against the running version before switching the boot partition. It covers native OTA, http_request.ota and web_server sources. One catch worth knowing: it only means anything if you're using signed OTA. Without signing, an attacker who can push firmware can push a version number too.

Does downgrade protection on a hobbyist temperature sensor sound like overkill? It did to me, right up until I remembered that these things sit on my home network with an open update path, and that anything with an open update path is a way in. If you haven't thought about where your sensors sit on the network, that's worth more of your attention than any changelog.

There's also a new transport-agnostic provisioning component, which matters more for people shipping devices to other people than for a home setup.

What Else Landed

Not everything in 217 pull requests is a hazard. The release runs a single-precision float sweep across roughly 50 components, which claws back memory on constrained boards. ESP8266 gets focused DRAM savings, which on a d1_mini is the difference between a config fitting and not. LVGL picks up animations, dynamic rotation and boot pausing. Eleven new components arrive covering touch controllers, e-paper panels, IMUs and the Divoom Pixoo 64. The new ESP32-S31 brings gigabit Ethernet, and ESP-NOW gets v2 payloads.

RTC-backed preferences on ESP32 is the one I'd flag as quietly useful. It means values survive a reboot without a flash write, which spares the flash on anything that restarts often. Flash wear isn't a theoretical problem on a node that reboots every time the power flickers, and I've lost a board to it before.

Should You Skip This One?

There's a temptation to sit this release out, especially if the Zigbee re-join sounds like a lost afternoon. It's an understandable instinct and I think it's the wrong one.

Breaking changes in ESPHome accumulate rather than expire. Skip 2026.7.0 and the re-join still waits for you in 2026.8.0, except now the Modbus split, the toolchain switch and whatever lands next month all arrive in the same evening. The deprecation timers keep running too: the image component keys die in 2027.1.0, web server version: 1 dies in 2027.1.0, and the rp2040 alias dies in 2027.7.0. None of those dates move because you waited.

The one good reason to wait is if you're mid-project on something fiddly. Finish the project, then upgrade. Otherwise the cheapest version of this migration is the one you do now, on your own schedule, rather than the one you do in a panic because a device died and the only build that works needs the new toolchain anyway.

What I'd Actually Do

Upgrade in this order. Nodes with no Zigbee, no Modbus and no HUB75 display first, because they'll almost certainly just work and you'll build confidence cheaply. Then the Modbus devices, with the new timing defaults in mind and a plan to re-tune them. Zigbee last, on a day you have hours rather than minutes.

Check the official 2026.7.0 changelog before you start. This page covers what breaks, not the full list of 217 changes, and the changelog is the source of truth if something here disagrees with it.

And if you're reading this because a build failed and you searched the error message, the answer is probably the toolchain default or the packages include syntax. Those two account for most of the confused questions I've seen since the release, and both are a one-line fix once you know which one bit you.