How to Update Immich Safely

How to update Immich with Docker Compose

To update Immich with Docker Compose, read the target release notes, make a database and media backup, update your mobile clients, and check IMMICH_VERSION in .env. Then run this in the directory containing your existing docker-compose.yml:

docker compose pull && docker compose up -d

Wait for startup and any migrations to finish, then test an older original, a new upload and its thumbnail. Preserve your existing .env, Compose file, storage paths and secrets. The official upgrading guide ↗ defines this routine workflow.

For an older v1 or v2 server, complete the v3 upgrade checks before using this command. If an update fails, use the failure checks. Downgrades, including within a minor version, are unsupported.

Before You Update Immich

Step 1: Check your current release and release notes

Record the server and mobile versions, database image tag and PostgreSQL major, explicit DB_VECTOR_EXTENSION if set, and any custom volumes, networks or hardware acceleration. An image tag in .env expresses intent; check the running application as well.

Choose the stable release you intend to install from the official Immich releases ↗. Read every release note between your running version and that target, including breaking changes. Compare the target release's Compose asset with your current file and transfer only the required service/image/environment changes while preserving your real paths and secrets. Official release files ↗

The exact-tag example in this guide uses the official v3.3.1 release ↗, checked on October 14, 2026. Recheck the release list before updating; an example tag is not a permanent recommendation to stay on that version.

Step 2: Back up the database and actual media

Follow the Immich backup guide before pulling new images. Keep a recoverable database dump and copies of managed originals, generated media as appropriate, and every external-library root. A database backup contains metadata and paths; it does not contain the photos and videos themselves.

Preserve the old Compose file, .env and custom configuration privately. Confirm that the backup can be restored on an isolated target with compatible versions. Keeping only old container images is not a rollback plan.

Step 3: Update mobile clients and check IMMICH_VERSION

Upgrade each mobile-client type you use before updating the server, following Immich's compatibility policy. The server is compatible with the matching major version; the mobile app is typically compatible with the current and prior major version. Versioning policy ↗

If .env pins IMMICH_VERSION, set it to the intended target, such as v3.3.1. If your policy uses the stable major metatag, v3 follows stable v3 releases and does not select release candidates. An exact old pin stays old after pull; do not assume the command changes it automatically.

Step 4: Pull the images and apply the update

In a terminal on the Docker host, enter the directory containing the active docker-compose.yml and .env. Validate edited configuration first:

docker compose config --quiet

Expected: no configuration error. If it fails, resolve the indicated YAML, file or environment problem without starting new services. This read-only command avoids printing resolved secrets. Docker config ↗

Run the official update command in that same directory:

docker compose pull && docker compose up -d

pull fetches the images selected by your configuration; up -d recreates or starts services with that configuration only if pulling succeeds. A pull failure means the update has not completed; check the target tag, registry access and available storage. Do not blindly overwrite the Compose file or .env with a release example.

docker compose restart restarts the existing containers; it does not apply new images or configuration. Use up -d for the update. Docker restart ↗

Step 5: Wait for startup and migrations

From the same Compose directory, inspect state and recent logs:

docker compose ps -a
docker compose logs --tail=100

Wait for intended services to remain running and report healthy where health checks apply, without repeated exits or migration errors. Some migrations and reindexing can take seconds to minutes on a large library or slower hardware; an error-free reindex is not a reason to interrupt startup. Docker status ↗, Docker logs ↗

Step 6: Verify services, media, uploads and jobs

Confirm the application reports the intended version. Log in from the web and each mobile-client type you use. Open and download an older original, play a video, upload a new test image and wait for its thumbnail. Test an external asset if you use an external library, then review search and people results for features you rely on.

Review Administration → Maintenance for new integrity findings and Job Queues for failed processing. A full integrity check examines beyond existing findings; refresh previously reported problems after correction. If thumbnails or originals fail, follow the image-loading troubleshooting guide. If the installation itself is unclear, compare it with the Docker Compose setup guide.

If the Immich update fails

If recovery is required, use the pre-update database, its matching software/configuration and corresponding media in the documented restore workflow. Reverting the image tag alone is not a supported downgrade. Keep failed-instance evidence until recovery has been verified.

How to upgrade to Immich v3

For a v1 or v2 installation, review the official v3 migration checklist ↗ before changing the server version:

• Database: v3 removes pgvecto.rs support. DB_VECTOR_EXTENSION=pgvecto.rs causes a startup error; complete the supported VectorChord transition below first.
• Machine learning: x86 CPUs must support x86-64-v2 or newer. Check the CPU features exposed to a virtual machine as well as the physical CPU.
• Configuration: replace removed machine-learning environment variables using the mappings in the official checklist, including any custom hardware-acceleration configuration.

After these checks and a successful database transition, use the Docker Compose update and verification steps above. Very old v1 installations may also need the intermediate upgrade described below. Servers already on v3 use the routine workflow unless their target release notes require additional steps.

pgvecto.rs to VectorChord

If the Compose database already uses ghcr.io/immich-app/postgres and you have not explicitly forced DB_VECTOR_EXTENSION, the official guide says it is already using VectorChord. Do not rerun a migration merely because an older blog contains it.

For the historical default pg14/pgvecto.rs 0.2.0 stack, the official transition image is ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0. Apply the complete relevant official migration diff ↗, not just one image line. If the original PostgreSQL or extension versions differ, use the corresponding transition image from the official instructions.

1. Take the pre-migration database and media backup and record PostgreSQL and extension versions.
2. On a compatible pre-v3 installation, apply the matching official database-image and configuration changes.
3. Start it and allow migration/reindexing to finish without errors.
4. Confirm the application is usable and the old forced pgvecto.rs setting is no longer required before selecting v3.
5. Take another recovery point after the transition, then perform the v3 update and verification above.

The official migration warns against downgrading below v1.133.0 after switching to VectorChord; the current general policy disallows downgrades altogether. Do not change PostgreSQL major versions by pointing a different image at the same data directory. A shared/custom database needs its own documented procedure. Pre-existing Postgres ↗

Very old v1: Invalid upgrade path

For an old v1 installation with Invalid upgrade path, follow the official historical intermediate-version requirement before continuing. The documented v1.132.3 guidance and source version determine the safe branch; do not invent a shortcut or skip intervening release notes. Errors ↗

Pre-v2.5 database backups also need version-selected restore instructions because the current UI recovery behavior changed in v2.5.0. Use the backup and restore guide ↗ for the matching software and database state.

Updating packaged NAS and LXC installations

Synology Container Manager, TrueNAS Apps, Unraid, native LXC and Docker-in-LXC may own different database and storage lifecycles. Preserve paths and backups, and use the distribution's supported controls rather than copying the default Compose command into a different packaging model.

Discussion #30621 ↗ records one community-tested path from v1.129.x through multiple checkpoints to v3; it is evidence from one environment, not an official requirement to visit every listed version. Discussion #25771 ↗ describes an unresolved community Synology updater issue and is not part of this runbook.

Sources

• Upgrading ↗ — Official update command, compatibility policy and VectorChord guidance.
• Official releases ↗ — Select a stable target and read intervening release notes.
• v3.3.1 release ↗ — Official release used for this guide's exact-tag example.
• Docker Compose ↗ — Official Compose release files.
• Backup and Restore ↗ — Official recovery prerequisites.
• Errors ↗ — Official historical upgrade/path errors.
• Migrating to v3 ↗ — Official breaking changes.
• Pre-existing Postgres ↗ — Official custom-database boundary.
• System Integrity ↗ — Official verification.
• Compose config ↗ — Official Docker reference.
• Compose ps ↗ — Official Docker reference.
• Compose logs ↗ — Official Docker reference.
• Compose restart ↗ — Why restarting alone does not apply an update.
• Old-version upgrade case, #30621 ↗ — Community evidence from one environment.
• Synology updater, #25771 ↗ — Community discussion; unresolved script failure.