Immich V3 Migration Runbook
Tech GuruQuick Answer
Before upgrading Immich to v3, preserve a consistent database and asset backup, the deployment configuration, and a working recovery path. Check removed environment variables, the database vector extension, API clients, and OAuth settings before changing the version. Test a restored copy first. A healthy container is not proof that photos, search, mobile backup, sharing, and authentication survived the migration.
Evidence status: The July 1, 2026 release and migration guide were checked. No library was migrated or restored, and no mobile, API, OAuth, or search test was performed. The steps below are a preparation and acceptance plan, not a tested deployment recipe.
What To Check
The migration guide says v3 removes pgvecto.rs support: DB_VECTOR_EXTENSION=pgvecto.rs causes an error. Resolve that dependency through the linked VectorChord migration documentation before attempting v3; changing only the image version does not migrate an unsupported database extension.
Keep originals, database records, derived data, deployment files, and external-library mounts distinct in the backup inventory. A database restored against the wrong asset set can start while leaving missing or mismatched photos.
Key Concepts In Plain Language
- Consistent recovery set: database and files captured through a coordinated backup procedure, with the configuration needed to reconnect them.
- API compatibility: the actual endpoints and response fields used by each integration, not just its ability to authenticate.
- Integrity versus indexing: missing or changed source files require different investigation from delayed search results.
Technical Checklist
- Pin the known-good v2 deployment and inventory database, assets, storage layout, environment variables, CLI jobs, API clients, OIDC, proxies, and mobile versions.
- Create coordinated database and asset backups, verify their size and readability, and retain the old compose or deployment definition.
- Stage v3 on a clone and test migration, integrity, search or indexes, API integrations, OIDC, mobile sync, uploads, downloads, and logout.
- Define rollback before v3 writes production data; restoring only the database or only the assets can leave references inconsistent.
Interactive Operating Model
Use the planned checks below with this overview. No test result is implied by the diagram.
Before You Start: Safe Defaults
Record server/mobile/CLI versions, database image and extension, asset locations, external libraries, proxy and identity dependencies. Keep the pre-change backup outside the working storage. Rehearse restoration without allowing the test system to modify production assets or accept production uploads.
- Confirm the exact installed release, edition, repository, firmware, and add-on state instead of relying on the dashboard label alone.
- Export configuration and protect application data, credentials, certificates, and encryption material separately.
- Stage on a clone, spare node, canary device, or least-critical workload whenever the platform allows it.
- Define stop conditions and console access before the maintenance window begins.
Go, Hold, Recover, Or Escalate
Hold the upgrade if the database extension is unsupported, recovery inputs are incomplete, or an essential integration has no compatible path. After v3 accepts new writes, reverting only the container image is not a recovery plan; preserve those writes and resolve consistency before restoring an older set.
Planned Checks And Recovery
The migration guide moves IMMICH_MACHINE_LEARNING_PING_TIMEOUT to machineLearning.availabilityChecks.timeout in the Admin UI, splits the CLIP/facial-recognition preload variables, and tightens OAuth URL/insecure-request behavior. Compare only relevant settings; do not replace a shared .env with a downloaded example.
The release instructions change IMMICH_VERSION to v3, then use docker compose pull && docker compose up -d. This is the vendor sequence, not authorization to run it on an unbacked library. Use the correct Compose project, review the chosen release, and complete the extension/recovery checks first.
Step 1: Restore before migrating
Restore the coordinated pre-change database and asset set to an isolated target. Open representative originals, albums and shared items. Confirm the copy cannot send real notifications or alter production libraries. Resolve missing files before introducing an upgrade.
Step 2: Map the breaking changes
Compare the deployment with the migration guide, including database extension, removed variables, machine-learning hardware requirements and OAuth. List the API calls and fields each tool uses; an HTTP success response alone does not establish compatibility.
Step 3: Upgrade the isolated copy
Apply the supported path for that installation. Retain migration logs and stop on database errors. Keep new uploads restricted until the library and identity checks pass. Treat index rebuilding as background work to observe, not permission to ignore missing originals.
Step 4: Exercise users and recovery
Test browser and mobile login/logout, upload/download, search, albums, sharing and each required API integration. Review the maintenance integrity report where available. Rehearse recovery of the consistent old set separately; account for any new writes before a production cutback.
Validation Checklist
- Restored originals open and match the intended database/library set.
- The database extension and deployed configuration satisfy the selected migration path.
- Mobile backup, search, API tools and OAuth have separate recorded outcomes.
- Missing/untracked/checksum findings are explained; no upgrade or rollback silently discards new assets.
Troubleshooting
- Server fails during startup: Compare the actual vector extension and migration error with the v3 requirements before retrying.
- Browser works but automation fails: Check removed endpoints, request fields and changed response shapes used by that tool.
- Search is empty: Distinguish unfinished indexing from missing assets using job logs and direct original-file access.
Security, Privacy, Legal, And Recovery Boundaries
Security
Use official packages and release guidance, preserve signing and authentication controls, and do not expose a management plane to simplify migration.
Privacy
Configuration exports and support bundles may contain names, addresses, tokens, certificates, device identifiers, and user data; encrypt and restrict them.
Legal
Review software licenses, support entitlements, and retention obligations before copying production data into a test environment.
Recovery
A rollback is credible only when its media, configuration, keys, data, boot path, and restore order are available outside the system being changed.
Record any local exception, its owner, its expiration condition, and the evidence required to remove it.
What The Evidence Does Not Prove
The cited release does not establish compatibility for every third-party tool or an exact recovery sequence for your storage topology. No backup consistency, migration duration, integrity result or restored-library test is reported here. The v3 major tag also does not identify an immutable point release.
Related TechGeeks Resources
- Linux and Homelab Notes: Start Here
- Homelab Backup Strategy: NAS, Offsite Copies, and Restore Tests
- How Do You Document a Homelab So Someone Else Can Recover It?
References
Next Action
Identify the database extension and restore one coherent library copy before scheduling the upgrade. Keep the integration results beside the recovery record.
