A Safe Immich Migration Checklist for a New Home Server
A safe Immich migration starts by proving what must survive before you copy anything: the photo files, the database, and the deployment settings that reconnect them on the new host.
On a home server, migration risk usually comes from moving those pieces at different times or starting the destination with the wrong paths. Treat the old server as the rollback copy, freeze avoidable writes, record the current version and storage mappings, then move one verified set of data to the new machine. The checklist below keeps the work reversible until the new instance can log in, find the original library, process jobs, and survive a reboot without falling back to an empty state.
Freeze the Source and Record the Known-Good State
Begin on the working server, not the new one. Record the Immich version, Compose or app-store definition, environment values that control database and storage paths, the location of the photo library, the database location, and any external-library mounts. Also note the current server URL and the user account you will use for validation.
The purpose of this inventory is to prevent a migration from quietly becoming an upgrade, a path redesign, and a network change at the same time. Keep the application version and logical storage layout as stable as possible until the restore passes; version changes can be handled after the destination is proven.
Before copying, stop or pause new uploads if your household can tolerate it. If that is not practical, define a cutover window and plan a final short synchronization. The exit from this stage is a written source map that lets you answer where originals live, where database state lives, and which configuration recreates the same relationships.
Capture Database, Assets, and Configuration as One Migration Set
Treat the database and media files as one recovery set rather than two independent backups. Current Immich database backups contain metadata and file references, not the photos or videos themselves, so the database backup must travel with the matching contents of UPLOAD_LOCATION and any external-library data you manage separately.
A usable migration set needs the assets, PostgreSQL state, and the configuration that reconnects them. A complete Immich backup set includes uploaded assets, a supported database backup, and deployment configuration, with restore testing used to prove the set works. Keep those pieces together so the destination can be matched to one recovery point.
Verify the migration set before touching the destination. Confirm that the database dump is non-empty, sample several original files from the copied library, and store the Compose and environment files in the same migration folder or documentation set. If any component cannot be verified, stop here and make a fresh copy rather than compensating on the new server.
Prepare the New Host Without Creating Competing State
Create the destination directories and mounts first, then confirm the new host sees the intended disks or network shares at the exact paths you plan to use. A missing NAS mount can leave an ordinary empty directory behind, and a container may happily initialize against that fallback path.
Install the runtime and recreate the deployment definition, but do not let a blank Immich instance accumulate uploads or configuration before the old state is restored. Keep credentials, database name, storage variables, and external-library mount targets aligned with the source unless the migration plan explicitly includes a controlled path change.
If the new server requires different host-side paths, map them deliberately while keeping the container-visible paths and database expectations coherent. The destination is ready only when its effective mounts point to the copied data locations and you can explain every path translation before the full application starts.
Restore the State and Reconnect Every Storage Path
Restore the database using the recovery path appropriate to the Immich version that created the backup, then start the remaining services only after the database is ready. Do not improvise destructive database commands from an older guide when a newer install uses a different restore workflow.
During cutover, keep the database and storage relationship intact before normal use resumes. A tested Immich migration sequence follows the same principle: the application should open against restored database state and the intended media paths, not initialize a fresh library and force a rebuild from scratch.
After startup, check storage access before launching heavy background jobs. Open several old assets across different dates, verify thumbnails load, confirm an album and a person or search result that existed before migration, and make sure external libraries are readable if you use them. A fresh onboarding screen or empty timeline is a stop signal: recheck database and mount mappings before writing new state.
Validate the Original Workload Before Retiring the Old Server
A successful first login is not the end of a migration. Upload one disposable test photo from the normal client, confirm it appears in the expected host storage, then delete it through Immich and verify the library remains healthy. This checks the complete write path instead of only proving that old data is readable.
Reboot the new home server and repeat the checks that matter to your household: browser login, mobile backup connection, several old photos, search, a representative video, job queues, and remote access if it is part of the normal setup. The migration is complete only when the same state survives a host reboot and the storage mounts arrive before Immich starts.
Keep the old server powered off but unchanged for a rollback window rather than immediately wiping it. If the new instance starts writing to an unexpected empty folder, cannot reproduce the old library after reboot, or shows database errors you cannot explain, stop new uploads and return to the known-good source while you compare the migration set. Retire the old host only after the destination has passed normal use and a fresh backup test.
Recommended products
Support & Tips
More to Read
How to Optimize Immich Database Connections for Concurrent Containers
Do not raise max_connections first. Measure Immich sessions, total every container's demand, preserve admin headroom, and tune only the proven bottleneck.
How to Prevent Duplicate Jobs or Imports in Immich
Separate repeated jobs from duplicate assets. Use one canonical ingestion path, control retries and path changes, then test re-entry on a small cohort.
How to Repair Immich After Its Database Volume Fills Up
Never delete PostgreSQL WAL to free space. Stop Immich writes, preserve database state, add safe capacity, recover PostgreSQL, then prevent recurrence.
