The same ESPHome YAML could produce a different configuration depending on the computer that compiled it. Change #21678 by Jonathan Swoboda, merged into the development branch on 26 October 2026, fixes that for the !include_dir_* tags by loading files in name order. The fix is expected in ESPHome 2026.11, unless it is backported to a 2026.10.x patch release first.

The problem

ESPHome's helper that collects files for !include_dir_named, !include_dir_list, !include_dir_merge_list and !include_dir_merge_named returned them in whatever order the filesystem listed them. On Linux with ext4 that is hash order; on Windows with NTFS it is alphabetical. Nothing sorted the result, and order matters in several places:

  • with !include_dir_merge_named, when two files set the same key, the file read last wins;
  • with packages: !include_dir_named packages/, packages declared later override earlier ones, so the package that won a conflicting option depended on the file order;
  • with the list variants, the order of the list, for example the order in which entities are created;
  • the config hash and the generated code could differ between machines for the same YAML.

So a config built in the Home Assistant add-on and the same config compiled on a Windows laptop could end up with different values for the same option, with no warning.

What changes

Directories and files are now sorted by name as ESPHome walks them. A directory's own files come first in name order, then each subdirectory in name order. "The later file wins" now means later in name order, on every machine.

One case now fails where it used to pass quietly. !include_dir_named also searches subdirectories but keys each file only by its file name, so dir/a.yaml and dir/sub/a.yaml both became key a, and one of them was silently dropped. That is now an error naming both files:

!include_dir_named: dir/a.yaml and dir/sub/a.yaml both use the key 'a'; rename one of them

A config with two files of the same name under one !include_dir_named directory used to load without one of them, and now stops with this message. Renaming one of the files fixes it. The author notes that no config in the ESPHome repository is affected.

Who should check

Anyone who splits device configs into directories, especially shared packages pulled in with !include_dir_named. If two files in such a setup define the same option, the winner is now decided by file names. Prefixing files with numbers, such as 10-base.yaml and 20-overrides.yaml, makes the intended order explicit.