Update Immich Safely Why Reading the Release Notes Is the One Rule You Never Skip
Immich improves fast, and every improvement arrives as an update. Most are painless. Some carry a breaking change — a database migration, a renamed setting — that punishes anyone who updates blind. The difference between the two experiences is a two-minute reading habit.
✍️ Technical Anshu🐳 Docker / Linux Server⏱️ 6 minute read
🎥 The install video gets you running — this guide keeps you running, month after month
Here is the honest shape of Immich ownership: the software is young, the developers move quickly, and the release notes are part of the product. Every Immich release publishes them, and occasionally one begins with a warning that a specific version jump needs a specific step, or must not be skipped past. Owners who read them glide. Owners who run a blind 'update everything' script eventually meet the release that bites — usually at the worst possible moment, with the family's only photo server down.
Before any Immich update — the 60-second checklist
☐ Read the new release notes, especially anything marked breaking change
☐ Confirm last night's backup of library and database exists
☐ Note your current version from the .env file — IMMICH_VERSION
☐ Update in the morning, not at midnight before a holiday
👆 Example pre-update checklist. Every item exists because skipping it has bitten real Immich owners.
1
Why Immich Updates Deserve More Respect Than Most
The project releases frequently — new features, fixes and internal changes arrive at a pace mature software never attempts
Some releases change how the database or file storage works. Applied in the right order, painless. Skipped across — jumping many versions at once — sometimes impossible without intermediate steps
The developers are not careless: breaking changes are announced in the release notes, in plain language, with instructions. The entire system works if you read them
Your photos are not a phone app you can reinstall. Downtime here means the family archive is offline, and a bad migration is a restore-from-backup event
2
The Safe Update Routine, Step by Step
Read the release notes for the version you are moving to — and for every version between yours and it, if you have skipped some. Look for the words 'breaking change'
Confirm your backup is current — library plus database, completed successfully. An update without a fresh backup is a gamble, not a routine
Download the fresh official files if the notes say so: some upgrades expect the current docker-compose.yml and .env from the release page. This is the step blind scripts always miss
Pull the new images: docker compose pull
Restart the stack: docker compose up -d
Verify, do not assume: open the web app, check your photo count, open a recent and an old album, run a face search, and upload one test photo from the phone
3
The Version Pin — Your Quiet Superpower
Your .env file carries an IMMICH_VERSION value, and understanding it gives you control:
Left at the default rolling setting, docker compose pull fetches the newest release — convenient, and exactly how people update into a breaking change by accident
Pinned to a specific version (for example a version tag like v1.x style values shown in the official example file), your server stays put until you change the number
The calm pattern used by many owners: pin the version, update deliberately once a month after reading the notes, and never update the day before you need the server to just work
Automatic update tools (Watchtower class) pointed at Immich remove exactly this judgement. If you use one anywhere else, keep Immich out of its reach
4
If an Update Goes Wrong
Do not keep restarting and hoping. Read the server container's logs — the error is almost always printed in plain sight
Check the release notes again for the migration step you may have missed; many 'broken' updates are one documented command away from healthy
If it is truly stuck: stop the stack, set IMMICH_VERSION back to your previous version, and start again — this is why noting the old version is on the checklist
The final safety net is the backup taken in step 2 of the routine. A restore is annoying. It is infinitely better than a corrupted only-copy — which is what updating without a backup risks
🔴 The one rule, stated once: never update Immich on autopilot. Ten calm, deliberate updates a year — notes read, backup checked — beat fifty blind ones. The release that bites is always the one nobody read about.
🎥 Watch the Complete Process in the Video
The video shows the install that starts your version history — every update after it follows the routine on this page.
Monthly is a sensible rhythm for most owners: frequent enough that you never face a giant version jump, calm enough that each update is a small, readable step. Security-related releases are the exception — read about those and apply them sooner.
Can I skip several versions and jump straight to the latest?
Sometimes, but the release notes for the versions in between decide — some releases must be applied in sequence because of database changes. If you have fallen far behind, update in stages following the notes rather than leaping. This is the strongest argument for the monthly rhythm.
My server broke after an update and I have no backup. What now?
Stop changing things and read the logs and the release notes for your exact version jump — most failures are a missed documented step and are recoverable in place. Treat it as the expensive lesson it is, and start the backup routine the same day the server recovers.
This guide is based on the Technical Anshu video linked above • Stuck on a step? Ask in the video comments — that is where answers come fastest 🙏