How to Prevent Immich Configuration Loss During Upgrades
Prevent Immich configuration loss during upgrades by treating the Compose file, environment values, database, upload library, and external-library mount definitions as separate persistent assets that must be captured and restored together.
A container is replaceable; the configuration around it is not. An upgrade can appear to erase Immich when a relative bind mount resolves from a different project directory, an environment edit never reaches the recreated container, or the new stack starts against an empty database. Inventory the active deployment first, keep versioned copies off-host, and prove a controlled recreation before production cutover.
Capture the Active Deployment Before Every Upgrade
Export the effective Compose configuration with secrets redacted, record image versions or digests, and copy the Compose and environment files to versioned storage. Inspect the running mounts rather than assuming the file in your editor launched the current containers. Pass means each runtime path maps to a known host location.
Record external-library paths, reverse-proxy settings, machine-learning URL, database connection values, user and group identity, network names, and any hardware acceleration devices. A missing item here becomes an unexplained post-upgrade difference later.
Community upgrade questions repeatedly show operators losing track of which Compose generation or environment layout applies. The useful lesson from one upgrade configuration discussion is to preserve the current working definition before translating it.
Back Up Database, Media, and Deployment Files Separately
Take a database-native backup plus a filesystem backup or snapshot of the upload library and deployment directory. Record start and completion times, archive sizes, and checksums. A backup that contains only Compose YAML can rebuild containers but cannot restore accounts, metadata, albums, or asset records.
Use a stopped backup for the simplest consistency boundary, or coordinate a live database dump and storage snapshot so their relationship is documented. Keep external libraries in the inventory even if Immich does not own their originals, because paths and access rules still affect the restored service.
A community-maintained major-version upgrade procedure emphasizes preserving database, media, Compose, and environment inputs. Treat its sequence as operator experience and confirm each step against the release you actually deploy.
Stage the Upgrade With Pinned Versions
Read the release notes for every skipped version and update the saved deployment definition deliberately. Pin the target release, pull it without removing old images, and validate the rendered Compose configuration. Unknown variables, empty mounts, or mixed service versions fail the staging gate.
Where capacity allows, restore the backup to an isolated test stack with different ports and no production write access. Start it on the target version and inspect migrations, users, storage paths, and background jobs. A successful container start alone does not prove the original library is attached.
The related ZimaSpace guide to a secure self-hosted NAS helps place deployment files and backups outside the single host and credential boundary that an upgrade can disrupt.
Prove Configuration Persistence After Recreation
Before cutover, recreate the test containers from the saved files rather than restarting them in place. Verify users, server settings, storage templates, libraries, jobs, proxy access, and effective environment values. Pass means configuration survives replacement because it lives in documented persistent components.
After production cutover, upload one test asset, run a search, open an original, and create a fresh database backup. Restart the stack and host, then repeat. Keep the old version, backup, and deployment definition until the normal workload remains stable through the observation window.
If the upgrade has already started empty, stop it before onboarding or new uploads create conflicting state. Reattach only a verified persistent path or restore into a clean target. Roll back when expected users or assets are absent; escalate with sanitized effective Compose, mounts, versions, and backup timestamps if identity remains ambiguous.
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.
