How to Move Immich Data Without Losing Users, History, or Settings
Move Immich as an application-state migration, not as a folder copy: preserve the database, media tree, configuration, secrets, and the paths that join them.
A migration can look successful because every JPEG exists on the new disk while accounts, albums, people, sharing, favorites, or historical relationships are missing. Build a rollback point first, capture one consistent source state, copy it without changing identifiers, restore on an isolated target, and cut over only after the household workflows match.
Inventory the State That Must Move Together
List the PostgreSQL database, uploaded media, generated data you intend to retain, external-library definitions, Compose or app configuration, environment values, secrets, network names, and the current storage mappings. Mark which item is authoritative and which can be regenerated after recovery.
A 2026 migration discussion about preserving Immich users during a move reinforces the central point: user and library state is tied to the database and mounted paths, not to the container image. Treat community commands as examples and adapt them to the exact deployed version.
Write down a small verification set before the move: two users, several albums, favorites, shared items, one person or search result, old and recent assets, and one external-library path if used. Those known records will make post-migration validation much stronger than comparing only total file size.
Create a Consistent Recovery Point Before Copying
Pause new uploads or schedule a maintenance window so the source stops changing while you capture the migration state. Take a database-native backup and protect the source media and configuration. Keep the original instance untouched after capture until the destination has passed verification.
The ZimaSpace recovery guide on restoring photo-library components together explains why originals, catalog state, and path-defining configuration must represent a compatible recovery point. That is the same boundary a migration needs.
Do not use the live production database directory as an ordinary file-copy target while it is changing. If downtime must be short, use a database-aware dump and a storage method whose capture order you understand. A migration is only as recoverable as the point you can restore, not the number of files copied.
Copy Media With Paths and Permissions Intact
Copy the media tree to the destination without reorganizing folders mid-migration. Preserve ownership, permissions, timestamps, and any filesystem features your deployment relies on. If the container-visible path is supposed to remain the same, change the host-side bind source while keeping the in-container mapping stable.
The current rsync migration workflow highlights archive mode, dry runs, resumable transfers, and the danger of destructive mirror options. Run a dry comparison before any deletion and verify the destination instead of assuming a completed command equals a complete application migration.
Compare file counts and sizes, then verify a representative checksum sample across old photos, new photos, videos, and large files. If copy errors or “vanished files” appear because the source changed, stop accepting uploads and repeat the differential pass rather than deleting the source to force a clean-looking destination.
Restore the Database and Configuration on an Isolated Target
Start the destination under a temporary hostname or isolated network so mobile clients cannot upload into it during validation. Attach the copied media at the expected container paths, restore the matching database, and reproduce the environment, secrets, networks, and proxy settings needed by that version.
A separate 2026 account of staged server migration shows why operators test the new host before retiring the old one. Use such reports for failure ideas, but let your known records determine whether the migration actually preserved state.
Stop if the destination opens as a fresh installation, reports missing storage, or proposes destructive initialization. Those symptoms usually mean the database or mounts are not the expected ones. Correct the path or restore target first; do not upload new files into an empty-looking instance and create two competing histories.
Cut Over Only After Users, History, and New Writes Pass
Log in as each reference user and verify album membership, favorites, sharing, search or people state, representative originals, timestamps, and the expected library counts. Then upload one new test photo and confirm that it appears, processes, and survives a container restart.
Change the production DNS or proxy target only after the isolated test passes. Keep the old instance stopped but recoverable so both systems cannot accept writes at once. Preserve the pre-migration database backup and source media until the new host has completed normal backups and at least one restore test.
Rollback if counts diverge, known relationships disappear, new uploads write to the wrong disk, or the destination fails after restart. Escalate with source and target versions, database backup timestamp, mount maps, copy logs, permission differences, and the first verification item that failed.
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.
