Guide: Safe Upgrade Path from Immich v1.129.x to v3.x (Docker Compose & VectorChord Migration)

[DorZvulun]

I recently upgraded my homelab Immich instance from v1.129.x all the way to v3.x.

Since I couldn't find a single end-to-end guide for upgrading from such an old version, I documented every checkpoint, every compatibility issue, and every verification step.

Hopefully this saves someone else a few hours (or days).

---

Test Environment

This guide was validated on my homelab.

Item | Value -- | -- Initial Version | v1.129.x Final Version | v3.x Deployment | Docker Compose PostgreSQL | 14 Database Size | 470 MB Assets | 24,851 Users | 2 Media | Photos + Videos OS | CachyOS

---

TL;DR

This upgrade path worked successfully:

v1.129.x
↓
v1.132.3
↓
v1.133.0
↓
VectorChord 0.3.0
↓
v1.135.3
↓
VectorChord 0.4.3
↓
v1.136.0
↓
v1.137.0
↓
v1.139.2
↓
v1.141.1
↓
v1.142.1
↓
v1.144.1
↓
v2.0.0
↓
v2.7.5
↓
v3.0.x

---

Why This Guide?

The official documentation is excellent, but it mostly focuses on upgrading from relatively recent versions.

If you're upgrading from something as old as v1.129.x, there are a few compatibility checkpoints that aren't obvious, especially around:

• pgvecto.rs → VectorChord migration

• PostgreSQL image compatibility

• required intermediate versions

• version-specific PostgreSQL images

This guide documents one successful production upgrade.

---

Before You Start

I strongly recommend having three backups before crossing major boundaries:

• PostgreSQL backup

• Media library backup

• Your Docker Compose / .env (or simply commit them to Git)

Before upgrading from:

• v1 → v2

• v2 → v3

I also created a fresh PostgreSQL backup.

Example:

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

---

Upgrade Path

Step 1

Upgrade:

v1.129.x
↓
v1.132.3

Only change:

IMMICH_VERSION=v1.132.3

Then:

docker compose pull

docker compose up -d

Verify:

• login works

• timeline loads

• server starts successfully

Do not continue until this version is healthy.

---

Step 2 — The Important One

Upgrade:

v1.132.3

↓

v1.133.0

This is where Immich migrates from:

pgvecto.rs

↓

VectorChord

---

IMPORTANT

Do NOT use the latest PostgreSQL image yet.

Use:

ghcr.io/immich-app/postgres:14-vectorchord0.3.0-pgvectors0.2.0

Do NOT use

ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0

yet.

---

Error We Hit

Initially I upgraded PostgreSQL to VectorChord 0.4.3 too early and received:

Error: The VectorChord extension version is 0.4.3,

but Immich only supports >=0.3 <0.4.

Please change VectorChord to a compatible version

in the Postgres instance.

The fix was:

1. downgrade PostgreSQL image to

14-vectorchord0.3.0-pgvectors0.2.0

2. complete the migration

3. upgrade Immich further

Only after upgrading to v1.135.x should you move PostgreSQL to VectorChord 0.4.3.

---

Verify Migration

Watch:

docker compose logs -f immich-server

You should eventually see:

Creating VectorChord extension

Reindexing clip_index
Reindexing face_index
Reindexed clip_index
Reindexed face_index
Dropping pgvecto.rs extension
Nest application successfully started

Only continue after:

• VectorChord created

• both indexes rebuilt

• pgvecto.rs removed

• server healthy

---

Step 3

Upgrade:

v1.133.0

↓
v1.135.3

Verify everything.

Now upgrade PostgreSQL image to:

ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0

Restart Docker Compose.

Verify:

• login

• uploads

• videos

• timeline

• search

---

Step 4

Continue through:

v1.136.0

↓
v1.137.0
↓
v1.139.2
↓
v1.141.1
↓
v1.142.1
↓
v1.144.1

No additional PostgreSQL changes were required.

At every checkpoint I verified:

• login (both users)

• timeline

• photos

• videos

• uploads

Only then did I continue.

---

Step 5

Upgrade:

v1.144.1

↓
v2.0.0

Before upgrading:

• PostgreSQL backup

Everything upgraded successfully.

Then:

v2.0.0

↓
v2.7.5

Again:

• verify

• backup

---

Step 6

Upgrade:

v2.7.5

↓
v3.x

Before upgrading:

• PostgreSQL backup

• Update mobile applications

No PostgreSQL changes were required.

Everything upgraded successfully.

---

Lessons Learned

• Don't jump directly from v1.129.x to the latest version.

• v1.132.3 is an important checkpoint.

• Immich v1.133 requires VectorChord 0.3.0.

• VectorChord 0.4.3 is introduced later.

• Upgrade Immich to v1.135.x before upgrading PostgreSQL to VectorChord 0.4.3.

• Verify the application after every checkpoint.

• Create PostgreSQL backups before major version upgrades.

• Don't replace your Compose file with the latest one immediately. Use the Compose version appropriate for the release you're upgrading to and only change what is required.

---

Verification Checklist

After every upgrade I checked:

• Server starts

• Both users can log in

• Timeline loads

• Photos open

• Videos play

• Upload works

• Search works

• No migration errors

• No database errors

Only after all checks passed did I continue.

---

Feedback Welcome

This guide documents one successful production upgrade path from Immich v1.129.x to v3.x using Docker Compose.

If maintainers or community members know of a shorter, safer, or more modern upgrade path—or if anything here becomes outdated—please let me know. I'll gladly update this guide so it continues helping users with older installations.

---

Credits

Huge thanks to the Immich maintainers for the release notes, migration documentation, and all the work that went into making these upgrades possible.

This guide doesn't replace the official documentation—it simply connects the individual upgrade notes into one complete end-to-end upgrade path for users coming from much older releases.

[Chocolladin]

Hello, Did this path, worked fine :

Version 3.1.0 installée le 17 août 2026
Version 1.136.0 installée le 17 août 2026
Version 1.132.3 installée le 17 août 2026
Version 1.129.0 installée le 16 mars 2025