Home Assistant releases a major update every month. Each release brings improvements — new integrations, performance work, security fixes — and occasional breaking changes that require configuration adjustments. For agricultural operations, updates are neither something to do immediately (the first release of any monthly version sometimes has rough edges) nor something to defer indefinitely (security fixes matter, and falling too far behind creates a larger upgrade effort later). A reasonable update discipline — read the release notes, back up before updating, give new releases a week or two to settle, update at a time that matches operational capacity, verify after updating, and maintain rollback capability — keeps updates boring. This page covers the update cadence, what breaks across releases, the staging pattern for operations that want to test before production, the specific steps around any update, rollback procedures when an update goes badly, and the specific failure modes that turn routine updates into operational incidents. Home Assistant is actively maintained; updates are part of the ongoing relationship with the project.
Before updating.
Prerequisites and framing.
A recent backup exists. Before any update, verify a current backup. If an update causes problems, the backup is the return path. An update attempt without a backup is a gamble; an update with a backup is a routine operation. [Backup and Recovery](/home-assistant/operations/backup) covers the backup discipline.
The release notes are read. The Home Assistant blog publishes detailed release notes for each version. Breaking changes are explicitly flagged; integration-specific notes are included. Reading these before updating is fifteen minutes of time that prevents hours of troubleshooting.
A sense of operational criticality. Some periods in an agricultural operation tolerate downtime better than others. A brief update window during off-hours in a stable phase is low-risk. The same update during flowering, during a transplant day, or during an extended absence is higher-risk. Time the update to the operation's capacity to absorb a brief outage.
Knowledge of the current version and the target. Home Assistant Core, Home Assistant OS, add-ons, integrations — each has its own version. Updating is not one thing but a coordinated set of changes. Knowing what is being updated and from what baseline matters.
The Home Assistant release cadence.
How updates arrive.
Monthly major releases. The first Wednesday of each month typically brings a major release (Home Assistant 2026.X, where X is the month). The release includes integration changes, UI improvements, performance work, and any breaking changes.
Point releases within the month. Between major releases, point releases (2026.X.1, 2026.X.2, etc.) fix bugs discovered in the major release. Point releases are more cautious than major releases; they rarely introduce new breaking changes.
Add-on releases. Add-ons update independently of Home Assistant Core. An add-on's release schedule depends on its maintainer. Some add-ons release frequently; others release rarely. The Supervisor shows available add-on updates.
Custom integration releases. HACS-installed integrations release on their own schedules. Staying current with HACS integrations matters — they are community software, sometimes with security issues or bug fixes that accumulate quickly.
Home Assistant OS releases. The underlying OS for Home Assistant OS installations. Updates less frequently than Home Assistant Core; usually brings supervisor improvements, OS-level package updates, and occasional larger changes.
Security releases. Out-of-cycle when specific security issues are identified. Rare but important; security updates deserve faster adoption than feature updates.
The update discipline.
The practices that make updates routine rather than incidents.
Read release notes. Every time. The breaking changes section is the important part; integrations with known issues or changes are listed. Fifteen minutes of reading prevents much troubleshooting.
Back up before updating. Not just "some recent backup" — a backup taken immediately before the update. If the update causes problems, this backup returns to the exact pre-update state.
Wait a few days after a major release. The first Wednesday release sometimes has issues that surface in the first few days. Letting a major release settle for a week gives time for point releases (2026.X.1, 2026.X.2) to address early issues. For operations that cannot absorb the risk of a newly-released version, this wait period is cheap insurance.
Update at a convenient time. Not late at night when a problem cannot be investigated. Not during a critical operational window. An hour or two of calendar time when investigation is possible if needed.
Verify after updating. Check the dashboard, run test scenarios, verify critical automations still work. Most updates work without issues; the verification catches the minority that need attention.
Document the update. Brief note of what version was installed and when. Useful for troubleshooting future issues that correlate with a specific update.
Staging environments.
For operations that want to test before production.
What staging provides. A second Home Assistant installation that receives updates before the production installation. Problems with an update show up in staging; production stays stable while staging is investigated.
When staging is worth the effort. Operations where updates occasionally go wrong; operations where downtime carries real cost; operations with complex configurations that are hard to troubleshoot under pressure. For smaller operations with simpler configurations, staging is overhead that may not be justified.
Staging options.
- A second hardware instance. The clearest pattern. A spare computer or Pi running its own Home Assistant instance that receives updates first. - A virtual machine. For operations with a capable host, a VM running Home Assistant alongside the production installation on different hardware. - A test configuration restored to a spare host occasionally. A lower-overhead approach: restore a recent production backup to a test host, update it, verify. Not a persistent staging environment but catches update problems.
Sync strategy. Staging should periodically sync from production — restore a backup from production to staging. This keeps staging's configuration close to production's; an update tested against an old staging configuration may not reveal problems the production configuration would face.
The cost. Hardware (modest), time to maintain (low but not zero), discipline to actually test before production (the hardest part). For operations that commit to the process, staging catches real issues before they affect the crop.
What typically breaks across updates.
Patterns observed across releases.
Custom integrations. Community-developed integrations are the most common breakage. Home Assistant's core APIs evolve; integrations that have not been updated to match break. The maintenance activity of specific community projects varies widely; well-maintained ones stay current, abandoned ones eventually stop working.
Deprecated configuration syntax. YAML configuration patterns that were valid in older versions get deprecated with warnings, then eventually removed. An installation that has not adjusted to deprecations hits the removal eventually. Release notes typically flag deprecations well in advance.
Integration-specific breaking changes. Individual integrations sometimes have breaking changes even when Home Assistant core's broader patterns do not. The affected integration's section of the release notes describes what to do.
Automation and template behavior changes. Subtle changes in how templates evaluate, how automation triggers match, or how specific services behave. Rare but possible; the release notes cover the known cases.
UI or dashboard changes. Cards or layout behavior that shifts between versions. Usually minor (appearance changes, not functional breakage); sometimes significant enough that custom dashboards need adjustment.
Add-on compatibility. An add-on that works with Home Assistant X may not work with X+1 until the add-on is updated. The Supervisor typically handles this by delaying the add-on update until compatibility is confirmed; sometimes issues slip through.
What usually does not break. Core functionality. Common integrations (well-maintained ones). Standard dashboards built with standard cards. The "boring" configuration patterns that many installations use. Home Assistant's stability for standard use is good; breakage concentrates in customization and community integrations.
The standard update procedure.
Step by step.
Step 1: Check the release notes. Settings → System → Updates shows what updates are available; the release notes link is there. Read the breaking changes section; note anything relevant to your installation.
Step 2: Back up. Settings → System → Backups → Create backup. Wait for completion. Verify the backup is listed and has a reasonable size.
Step 3: Disable or pause anything time-sensitive. If a critical scheduled automation is expected to fire soon, either wait for it to run before updating or confirm that a brief restart will not disrupt it.
Step 4: Start the update. Settings → System → Updates → Install. Home Assistant applies the update and restarts. For Home Assistant OS, this can take several minutes; for Container installations, the update is typically faster.
Step 5: Verify after restart. Home Assistant restarts; dashboards load; entities are present. Run quick spot checks on critical automations. Look at the log for new errors.
Step 6: Let it run. For 30 minutes to an hour, watch for unusual behavior. Most issues surface quickly; some take a bit longer.
Step 7: If something is wrong, assess. Minor issues (a specific integration reporting errors) can usually be addressed without rolling back. Major issues (core functionality broken, many entities unavailable) call for rollback.
Step 8: Document. Brief note of the update date, the version installed, and any issues encountered. Future troubleshooting benefits.
Rolling back an update.
When an update goes wrong.
The rollback path. Restore the pre-update backup. Home Assistant OS and Supervised installations have specific rollback procedures; Container installations involve swapping the image version and restoring configuration.
Home Assistant OS rollback. Settings → System → Backups → [pre-update backup] → Restore. The restore applies the backup, which includes the pre-update version.
Home Assistant Core version rollback for Container deployments. Change the image tag in the Docker Compose configuration to the specific previous version; restart the container. The previous version's state continues from the last time it ran.
Add-on rollback. Individual add-ons can often be rolled back through Supervisor if the add-on maintains version history. For custom add-ons or add-ons without version history, a broader backup restore is the path.
When rollback is hard. If Home Assistant's database format changed between versions, rolling forward then back can leave a database that the older version does not understand. This is rare but real; backup-and-restore avoids this because the backup contains the version-consistent database.
Testing rollback. As with backup/restore, the first rollback attempt should not be during an actual problem. Practice on a test system; understand the specific procedure for your installation type; have confidence before the real need arises.
Managing integrations and add-ons separately.
Versions are not one thing.
Core Home Assistant version. The main Home Assistant application. Major monthly updates.
Supervisor and OS versions (for Home Assistant OS and Supervised). The underlying supervisor and OS. Independent update cadence from Core.
Add-ons. Each add-on has its own version and update mechanism. Some auto-update by default; others require manual approval.
Custom integrations (HACS). Each HACS integration has its own version. HACS shows available updates; applying them is per-integration.
ESPHome device firmware. ESPHome devices have their own firmware versions. OTA updates through the ESPHome integration handle this; each device updates individually.
Zigbee2MQTT firmware. The add-on itself, plus the Zigbee coordinator's firmware, plus potentially device firmware. Each is a separate update.
The coordination challenge. Updates are not atomic across all these. A Home Assistant Core update may affect add-on compatibility; an add-on update may require a specific Home Assistant version; an integration may need both. The Supervisor handles most coordination; occasionally the grower needs to manage the dependencies explicitly.
Update strategies.
- All-at-once. Update everything available in one session. Faster; more changes to diagnose if something breaks. - One-at-a-time. Update Core first, verify, then add-ons, verify, then custom integrations. Slower; clearer attribution if something breaks.
Most operations fit somewhere between — batch core and supervisor, then separately address add-ons and custom integrations.
Breaking changes and how to handle them.
When the release notes say "breaking change," here is what that means in practice.
The typical pattern. An older feature (integration, configuration option, service) is deprecated for several releases — still functional, but with log warnings indicating it will be removed. Eventually the feature is removed. Installations that were heeding the warnings have already migrated; installations that were not hit an incompatibility.
The response. The release notes describe the migration. For configuration changes, the new syntax is shown. For integration changes, the replacement integration or updated approach is named. Following the release notes' guidance resolves the breaking change.
The deeper discipline. Responding to deprecation warnings when they appear, not when the removal hits. The warning phase is typically several months; acting on the warning prevents the surprise.
Deprecation tracking. An operational practice: when a release note announces a deprecation, log what needs to change. When capacity allows, make the change. Over time, deprecations do not accumulate into crisis.
When breaking changes affect critical functionality. Sometimes a core feature that the operation depends on changes or is removed. The release notes warn; migration is required. For operations caught without preparation time, the choices are: update and migrate quickly; defer updating while preparing the migration (accepting the security and feature-freeze trade-off); or find an alternative if the feature is truly gone.
Update cadence decisions.
How fast to follow the releases.
Aggressive: update within days. Follows the project closely; gets new features quickly; also hits the occasional rough edge. Appropriate for operations that can absorb occasional issues and that want to stay current.
Moderate: update within a week or two. Waits for the first point release (2026.X.1) which typically fixes early issues. Good balance between staying current and avoiding rough edges. The recommendation for most agricultural operations.
Conservative: update monthly, after the first point release, during planned windows. Stays two to four weeks behind the leading edge. Lowest risk of update surprises; may miss out on specific new features.
Extra-conservative: skip occasional releases, update every two months or more. Risks accumulating deprecation warnings; larger gaps between updates mean more changes to absorb at once. Usually not the right choice unless specific circumstances justify it.
Security-driven. Security updates, when they are released out-of-cycle, deserve faster adoption regardless of the general cadence. Waiting weeks for a security update is not the same trade-off as waiting weeks for a feature update.
The cadence choice is revisable. Operations that started aggressive can become more conservative after a few surprises; operations that started conservative can become more current as they build confidence. The choice fits the operation's current state, not a permanent position.
Preparing for larger upgrades.
When the operation has fallen behind.
The scenario. An operation that has not updated Home Assistant in many months (or years). Dozens of release notes worth of changes and deprecations have accumulated. The jump from current version to the latest is larger than any single update.
The approach. Staged upgrade — update in steps rather than one large jump. Update to each intermediate version; verify; continue. This is slower than a direct jump but much safer — each step is recoverable, each step's issues are smaller, each step's release notes inform what to check.
Preparation. Back up thoroughly. Review the release notes for every intermediate version. Identify breaking changes that apply to the installation. Plan the migration path; sometimes an intermediate version is a deliberate stopping point to complete specific migrations.
Time estimate. For an installation several major versions behind, the staged upgrade can take hours to days (counting verification time). Budget accordingly; do not attempt during a critical operational window.
When to consider from-scratch. For installations very far behind, with extensive custom configuration, from-scratch rebuild on a current version may be faster than staged upgrade. This is a larger project but results in a clean current installation. The trade-off depends on how much configuration exists and how complex it is.
Common failure modes.
Specific update-related problems from real deployments.
The update that was applied without reading release notes. A breaking change affected a critical automation; the grower did not know until the automation failed to fire; investigation revealed the breaking change was documented. Fix: read release notes before updating; fifteen minutes of reading prevents hours of troubleshooting.
The update during a critical window. Home Assistant was updated during flowering transition; something broke; the critical automation did not fire; crop stress occurred before recovery. Fix: time updates to the operation's capacity to absorb brief issues.
The update that succeeded but the custom integration was not updated. Home Assistant core updated; a HACS integration was not updated to match; the integration failed silently until its automations did not fire. Fix: include custom integrations in the update planning; check HACS for updates after core updates.
The rollback that did not work. An update went badly; the grower tried to restore from backup; the restore failed (for any of the reasons in the backup recipe). Fix: practice rollback before needing it; the first rollback attempt should not be during a crisis.
The update that broke device integrations that seemed unrelated. A core change affected how device polling worked; devices that had been running reliably started timing out. Fix: verify critical device integrations after core updates; the cause-and-effect between core and integrations is not always obvious.
The long-deferred update that broke cumulatively. An installation that skipped six months of updates attempted to catch up in one jump; many things broke; diagnosis was difficult because multiple deprecations had accumulated. Fix: stay current on a reasonable cadence; staged upgrades for catching up.
The update that changed UI behavior subtly. A dashboard that worked fine before the update rendered differently after; cards were positioned wrong; the primary quick-check view was confusing. Fix: verify dashboards after updates; custom cards may need updates to match.
The Supervisor update that had issues while a core update was pending. Supervisor updated; core update afterward failed due to some intermediate state. Fix: follow the recommended update order (Supervisor before Core typically); separate the updates in time if needed.
The update that was applied to the wrong thing. The grower intended to update a specific add-on but accidentally updated core; breaking changes hit. Fix: attention during update operations; verification of what is being updated.
The rollback that lost recent data. The restore brought back the pre-update configuration and pre-update database; work done between the backup and the problem was lost. Fix: accept that rollback loses post-backup changes; minimize the window between backup and update; for important work, back up immediately before to keep the window small.
What not to do.
Patterns to avoid.
Don't skip reading release notes. The fifteen minutes of reading is the most valuable fifteen minutes in the update process.
Don't update without a fresh backup. The backup is the insurance policy. Skipping it is betting that nothing will go wrong.
Don't update during critical operational windows. The time for updates is when the operation can absorb a brief disruption. Flowering transitions, pest pressure, transplant days — these are not the times.
Don't let security updates wait. Feature updates can wait for convenience; security updates should not wait more than a few days.
Don't defer updates indefinitely. Falling too far behind creates larger upgrade projects, more accumulated deprecations, and higher-risk catch-up. Reasonable cadence is both safer and easier.
Don't run on abandoned custom integrations. Community integrations that have stopped being maintained will eventually break on Home Assistant updates. Identify these; find alternatives; do not count on them for critical operations.
Don't ignore deprecation warnings. Warnings announce future breakage. Acting on the warning during the deprecation window prevents the breakage during the removal.
Don't update multiple things simultaneously when troubleshooting. If an update caused issues, fix one thing at a time. Changing multiple things at once obscures which change mattered.
Don't treat rollback as hypothetical. Know the rollback procedure for your installation. Practice it. The first real rollback should not be the first rollback you have ever attempted.