Updates: Core, Supervisor, OS, and Add-Ons Without Surprises
Updates: Core, Supervisor, OS, and Add-Ons Without Surprises
An update run on reflex, without reading the release notes, is the most common reason integrations suddenly stop working. This lesson covers the four layers of the system you update separately, how to read the Breaking Changes section before clicking Update, and a safe order and moment to actually run an update.
Budget around 60 minutes. I'm assuming you already have a tested backup from the previous lesson: without it, this lesson is purely theoretical.
Four Layers You Update Separately
| Layer | What it covers | Update frequency |
|---|---|---|
| Home Assistant Core | logic, integrations, the automation engine | monthly, major releases |
| Supervisor | managing add-ons and updates (HAOS/Supervised installs only) | less often, alongside patches |
| Operating System (HAOS) | the underlying operating system | a few times a year |
| Add-ons | Mosquitto, the ESPHome Dashboard, File Editor, and others from across this course's modules | independently, each on its own schedule |
This distinction matters, because each layer updates independently and can carry different compatibility requirements. It's also worth keeping a separate, fifth layer in mind: HACS integrations, covered in more detail in this module's Lesson 9, which update outside Home Assistant's main update mechanism.
How to Read the Release Notes Before Clicking Update
Every major Home Assistant Core release has a Breaking Changes section, spelling out exactly which integrations change behavior in a way that could break an existing configuration. That's the first thing to read before you click Update, especially if your install uses any of the integrations listed there.
The Breaking Changes section: check whether it names integrations you actually use in your system
The full release changelog: available on the official Home Assistant site, worth at least a quick skim
The community forum and GitHub Issues: if a release is very fresh, it's worth waiting a few days and checking whether others are reporting problems
A Safe Order and Moment to Update
1. Check the date of your last backup: if it's older than a few days, run a fresh one by hand before updating.
2. Read the Breaking Changes for the version you're updating to.
3. Update at a moment when you have time and energy for a possible fix, never right before leaving the house or going to sleep.
4. Update one layer at a time: Core first, wait, check that everything works, only then move to the next one.
5. After updating, check the System Log and Repairs (this module's Lesson 5) for new warnings.
A growing gap from the current version raises risk
The longer you put off updates, the more changes land in your system at once in a single update, which makes it harder to diagnose exactly which change caused a problem. Regular, smaller updates are safer than rare, large version jumps.
Stable Channel Versus Beta: Is It Worth Testing New Features Early
Beyond the standard stable channel, Home Assistant also offers a beta channel, letting you install an upcoming version before its official release. That's convenient for enthusiasts wanting to report bugs to the development team, but for a home install real safety automations depend on, the beta channel carries noticeably higher risk of unfinished features. A sensible rule: the beta channel on a separate test install (a virtual machine, say), the stable channel on your production install.
Four Ways to Install Home Assistant, and How They Affect Updates
| Install method | What updating looks like |
|---|---|
| Home Assistant OS (HAOS) | the full set of four layers from this lesson, updated through the built-in interface |
| Home Assistant Container | updating by pulling a new container image, with no Supervisor or add-ons |
| Home Assistant Core (Python venv) | manual update via pip, the most flexible option, but requiring the most hands-on work |
| Home Assistant Supervised | a deprecated install method, officially discouraged since 2025.12 in favor of HAOS |
Supervised install deprecation
A Supervised install on a bare operating system (without HAOS) was officially removed from the recommended install paths in late 2025. If you're still running this type of install, it's worth planning a migration to Home Assistant OS, following the process described in this module's Lesson 7.
What a Well-Prepared Pre-Update Note Looks Like
Experienced Home Assistant users, before clicking Update, leave themselves a short note: the current version, the planned version, the list of integrations named in Breaking Changes, and the date of the last backup. A note like that takes literally a minute to write, but if something goes wrong, it gives you a ready reference point instead of guessing exactly what changed. That same note later becomes an entry in the maintenance log built in this module's Lesson 10.
Plan B: What to Do When an Update Does Break Something
Even following every rule in this lesson, an update occasionally reveals an unexpected problem. Home Assistant OS keeps the previous system version, allowing a rollback (reverting to the previous version) directly from the interface under Settings, System, Updates. For Core itself, a rollback requires restoring the backup taken right before the update, which again underscores why this module's Lesson 2 is the foundation everything else rests on.
Release Notes Worth Extra Attention for This Course's Users
Because this course leans heavily on integrations like Zigbee (Module 9), ESPHome (Module 10), Music Assistant (Module 22), and weather integrations (Module 21), it's worth paying extra attention at every update to any mention of exactly these components in the release notes, even if the rest of the Breaking Changes doesn't apply to you. These integrations are among the most actively developed in the whole Home Assistant ecosystem, so changes to them show up more often than in more stable, less frequently updated parts of the system.
Add-Ons and HACS: A Separate Update Rhythm Outside Core
Beyond the four main layers, add-ons like Mosquitto from Module 6 or Frigate from Module 21 update independently, each at its own pace, shown as separate notifications under Settings, Add-ons. The same applies to integrations installed through HACS, covered in more detail in Lesson 9: they have an entirely separate update mechanism, controlled from the HACS panel, not from Home Assistant's main Updates screen.
In practice, this means a full update review covers three places in the interface: the main Updates screen (Core, OS, Supervisor), the Add-ons tab, and the HACS panel separately. Skipping any one of them leads to part of the system lagging weeks behind the rest.
How to Test This Lesson
1. Find the Breaking Changes section for the latest available Core release in your install.
2. Check whether any of the integrations listed there are used in your system.
3. Schedule your next update for a specific, convenient time, not on reflex.
Common Mistakes
Updating without reading Breaking Changes: the most common reason integrations suddenly stop working after a restart
Updating every layer at once: makes it harder to diagnose which change caused a specific problem
Updating right before leaving the house: no time to fix things if something goes wrong
Practical Task
☐ Pick a fixed, convenient time for regular updates (the first Saturday morning of the month, say).
☐ At your next update, work through this lesson's full order of steps.
Key Takeaways
Four update layers: Core, Supervisor, the operating system, and add-ons, each independent.
Breaking Changes is the first section to read before any update.
Regular, smaller updates are safer than rare, large version jumps.
What's Next
Next lesson: The Database and the Recorder: Why Home Assistant Slows Down After a Few Months. This is the second most common source of frustration after failed updates.
