Immich 3.0 Upgrade: What Breaks and How to Update Safely From 2.x

Short answer: Immich 3.0 (v3.0.0) was released on 2 July 2026, and the newest v3 patch at the time of writing is v3.3.5 (21 October 2026). For a standard Docker Compose install, the official upgrade is two steps: change IMMICH_VERSION=v2 to IMMICH_VERSION=v3 in .env, then run docker compose pull && docker compose up -d. Before that, update every phone to the latest Immich app, take a database dump, and confirm your database already uses VectorChord, because v3 drops pgvecto.rs entirely. Immich does not support downgrades, so your backup is your only way back.

Official-source review — 24 October 2026 UTC: We checked the Immich v3.0.0 GitHub release notes, the v3.0.0 and “Migrating to v3” posts on immich.app, the Upgrading and Backup and Restore docs, and the v3.3.5 release with its official docker-compose.yml and example.env. We did not install, upgrade or run Immich ourselves. Every snippet below comes from Immich’s own files and is labelled as such.

Who needs to worry about the Immich 3.0 upgrade

Immich’s release notes say many of the breaking changes “affect only third-party tools” that use its API, and that for most users “updating works exactly as it always has.” Slow down if any of these apply to you:

• Your database still uses the tensorchord/pgvecto-rs image, or .env sets DB_VECTOR_EXTENSION=pgvecto.rs.
• You set machine-learning environment variables by hand.
• You use OAuth over plain HTTP.
• Third-party tools, scripts or metrics dashboards talk to Immich.
• The machine-learning container runs on an older x86 CPU.
• Someone in the household still runs an old mobile app.

Starting from scratch? Follow our Immich install guide instead.

Is there a minimum version before upgrading to v3?

Immich does not name a minimum 2.x release you must be on first. The only stated requirement is about the database extension. The v3.0.0 release notes warn that v3 “drops support for pgvecto.rs,” and that if you ran Immich before v1.133.0 and never did the migration step, you must follow the VectorChord migration guide first.

The Upgrading documentation gives a simple test. If you deploy with Docker Compose, your database image is ghcr.io/immich-app/postgres, and you have not set DB_VECTOR_EXTENSION, you already use VectorChord. This quick check is our own suggestion, not an Immich command:

grep -n "image:" docker-compose.yml
grep -n "DB_VECTOR_EXTENSION" .env docker-compose.yml

If the database line shows tensorchord/pgvecto-rs, do the VectorChord migration below while you are still on v2. Do not combine it with the major version jump.

What changed in v3 and what you must do

This table summarises Immich’s v3 migration guide. API changes share one row because they only affect third-party tools and scripts.

Back up the database before you touch anything

Immich keeps file paths and metadata in PostgreSQL. Its docs stress that a database dump does not contain your photos or videos, so you need both the dump and a copy of your UPLOAD_LOCATION folder.

Immich makes automatic daily dumps in UPLOAD_LOCATION/backups (by default it keeps the last 14). For a fresh one just before upgrading, go to Administration > Job Queues, click Create job, choose Create Database Dump and confirm. From the command line, Immich’s documentation gives this backup command for Linux:

# From the Immich Backup and Restore docs. Replace the placeholders
# (usually "immich" for the database and "postgres" for the user).
docker exec -t immich_postgres pg_dump --clean --if-exists --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME> | gzip > "/path/to/backup/dump.sql.gz"

Copy the dump off the Immich host. A NAS snapshot (see TrueNAS vs Unraid) or a Proxmox VM snapshot (see our Proxmox VE guide) is a useful extra layer, but it does not replace the dump.

Migrating from pgvecto.rs to VectorChord (only if needed)

Do this on v2, and only if the check above showed the old image. The Upgrading documentation shows the following change to the database service. This excerpt is from Immich’s docs and has been shortened:

# Excerpt from docs.immich.app/install/upgrading (Immich), shortened
  database:
    container_name: immich_postgres
-   image: docker.io/tensorchord/pgvecto-rs:pg14-v0.2.0@sha256:...
+   image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    environment:
      ...
+     # Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
+     # DB_STORAGE_TYPE: 'HDD'
-   healthcheck: ...   (whole block removed)
-   command: ...       (whole block removed)
+   shm_size: 128mb
    restart: always

The removed health check and tuning lines are now built into the image. If you changed the defaults (PostgreSQL 14, pgvecto.rs 0.2.0), match the new tag to your versions; the docs’ example turns pg16-v0.3.0 into 16-vectorchord0.3.0-pgvectors0.3.0. On first start, logs can look stuck at Reindexing clip_index or Reindexing face_index on large libraries or weak hardware. Immich says this is normal if no errors appear. Our Immich hardware requirements page explains why the database belongs on an SSD.

Step-by-step Immich 3.0 upgrade checklist

1. Read the notes for v3.0.0, the “Migrating to v3” post, and every v3.x patch you will install.
2. Update the mobile apps. Immich’s versioning policy says the app is typically compatible with the current and prior major version, but the server only works with its matching major version. Update every phone first.
3. Check third-party tools. Make sure anything that uses the Immich API has a v3-compatible release.
4. Back up. Create a database dump and copy your UPLOAD_LOCATION off the host.
5. Confirm VectorChord. If you still use pgvecto.rs, migrate on v2, start Immich and wait for reindexing to finish.
6. Clean up env vars. Remove or replace the three removed machine-learning variables, and fix OAuth if it uses HTTP.
7. Change the version tag. Edit .env as shown in Immich’s release notes:

   # From the Immich v3.0.0 release notes
   - IMMICH_VERSION=v2
   + IMMICH_VERSION=v3

8. Pull and restart. In the folder with docker-compose.yml, run:

   docker compose pull && docker compose up -d

9. Watch the logs. Run docker compose logs -f immich-server until startup finishes, then sign in on the web and on a phone.
10. Tidy up. Once everything works, the docs suggest docker image prune to remove old images.

Immich says major-version tags such as v3 do not follow release candidates. The official example.env for v3.3.5 already contains IMMICH_VERSION=v3, and its compose file uses the ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0 image. The same commands work under Docker Desktop.

Rolling back if the upgrade goes wrong

Immich’s Upgrading page says downgrading to an earlier version “is not supported,” even within the same minor version. After moving to VectorChord, you should not run any version below 1.133.0, and a backup made after the switch needs a database image that includes VectorChord to restore.

So rolling back means restoring. Under Administration > Maintenance > Restore database backup, Immich lists dumps with their version and makes a restore point first, though it warns that a backup from a different version may need migrations. To return to v2, set IMMICH_VERSION=v2 and restore your pre-upgrade dump using the command-line steps in the Backup and Restore docs. Those steps wipe the current database, so read them in full first. We have not tested this path.

After the upgrade

Check that phone backup still runs, smart search and faces return results, and remote access still connects (our Tailscale vs WireGuard guide covers both options). Still moving your library across? See Google Photos to Immich. Official links are on our Immich page. If Home Assistant shares the host, check its install method before pruning images.

Questions

Can I upgrade straight from any 2.x version to 3.0?

Immich does not publish a minimum 2.x version. The stated requirement is that your database has already moved off pgvecto.rs. Read the notes for the releases you are skipping, and back up first.

Will the old Immich mobile app work with a v3 server?

Do not count on it. Immich says the server only works with its matching major version of the app. Update the apps before the server.

Do I need to replace my whole docker-compose.yml for v3?

No. The release notes only ask you to change IMMICH_VERSION. The database image change applies only if you are still on pgvecto.rs.

How long does the upgrade take?

Immich gives no fixed time. The docs say the database changes after a VectorChord switch can take “seconds to minutes,” depending on hardware and library size.

Sources

• Immich v3.0.0 release notes (GitHub)
• Immich blog: Release v3.0.0
• Immich blog: Migrating to v3
• Immich v3.3.5 release notes (GitHub)
• Official docker-compose.yml attached to v3.3.5
• Official example.env attached to v3.3.5
• Immich docs: Upgrading (versioning policy and VectorChord migration)
• Immich docs: Backup and Restore
• Immich docs: Standalone PostgreSQL
• VectorChord repository (TensorChord)