How to update Immich safely (Docker Compose checklist)

Immich ships updates often, and most of them are small. The update command itself is one line. What goes wrong is everything around it: no backup, a skipped breaking change, or a phone app that no longer talks to the server. This checklist covers the steps that keep an update boring.

It assumes the standard Docker Compose install from the official docs.

Before you update: the two things you must back up

Immich keeps your library in two places, and you need both:

The Postgres database. Albums, faces, people, metadata and users live here. Lose it and your photos turn into an unsorted pile of files.
Your UPLOAD_LOCATION folder. The original photos and videos.

The official backup and restore guide shows a database dump along these lines (replace the names if you changed the defaults):

docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres | gzip > immich-pre-update.sql.gz

Also copy your docker-compose.yml and .env. Better still, keep them in Git so you can see exactly what changed.

One warning from that same guide: the backup and restore process changed in v2.5.0. If your backup came from an older version, use the docs version selector to find the restore steps that match it.

Check for breaking changes (and update phones first)

Read the release notes for every version between yours and the target. The Immich docs keep a list of releases with breaking changes.

Two rules from the versioning policy:

Breaking changes are meant to land only in major versions (v2 → v3).
The mobile app usually works with the current and previous major version, but the server only works with its own major version. Update the phone apps before the server.

Going from v2 to v3? Read the v3 migration post first. It lists removed environment variables and API changes.

You can also check the Immich page on SafeToUpdate. Each release gets a plain-English risk verdict based on the release notes.

Pin your version instead of using latest

In .env, set an exact version. At the time of writing, the latest stable release is v3.3.5 (October 21, 2026):

IMMICH_VERSION=v3.3.5

That way an update only happens when you decide it does. If you’d rather get patches automatically, the docs say you can use a major-version tag like :v3, which stays inside one major line. Our guide to pinning image tags and backing up volumes covers the same idea for every container.

Don’t replace your compose file with the newest one from GitHub unless the release notes tell you to. Change only what the release requires.

Run the update

From the folder that holds docker-compose.yml:

docker compose pull && docker compose up -d

That’s the official command (source). Once you know the new version works, you can clear out old images with docker image prune.

On bigger updates, Immich may run database migrations on startup. According to the docs, logs can look stuck on lines like Reindexing clip_index for a while on large libraries or slow hardware. If there are no errors, wait.

Check it actually worked

Watch the logs:

docker compose logs -f immich-server

Then do a quick check by hand (adapted from a community upgrade guide):

Server starts with no database or migration errors
Every user can log in
Timeline loads and photos open
Videos play
A test upload from your phone works
Search and face recognition return results

Keep your backup until you’ve used the new version for a few days.

If something breaks

The docs are blunt about this: downgrading isn’t supported, even within the same minor version (source). Setting the old version number back is not a rollback. Your options:

Read the error in the logs and look it up in the release notes and GitHub issues. Most problems turn out to be a missed config change.
Restore the database dump you took, following the restore steps for your version. A database restore needs a fresh database, and the guide explains the DB_SKIP_MIGRATIONS=true trick for setups where the server starts along with the database.

This is why the backup step comes first.

Jumping several versions? Go in steps

If you’ve fallen far behind, don’t jump straight to the newest release. A community guide on GitHub describes upgrading from v1.129 to v3 through checkpoints (v1.132.3, then v1.133.0 for the VectorChord database change, and so on), with a health check after each one. The official docs also warn that once you switch to VectorChord, you shouldn’t go below 1.133.0.

The rule: one checkpoint at a time, back up before each major boundary, and don’t move on until the current version works.

FAQ

How often should I update Immich? There’s no official schedule. The project doesn’t backport fixes to older versions and recommends running the latest stable release (source). Updating regularly keeps each jump small. Security fixes are a good reason not to wait: the v3.3.5 release notes recommend updating as soon as possible because of a certificate-authority fix.

Can I use Watchtower to auto-update Immich? You can, but auto-updates skip the step where you read breaking changes. If you automate, pin to a major tag such as :v3 and keep automatic database backups running.

Do I need to stop Immich to back it up? The backup guide suggests stopping immich-server during the backup when you can, so the files and the database match.