What Is Immich State, and Which Parts Must Persist?
Immich state is the combined media, database, identity, configuration, and derived data required to reproduce the library’s intended behavior.
The original files are essential, but they are not the whole application. Albums, users, ownership, faces, search representations, path mappings, and secrets determine how those files appear and who can use them; some are authoritative, while others can be rebuilt at a cost.
Original Media and Database Relationships Form the Core
Original photos and videos preserve the irreplaceable content. The database preserves how Immich understands that content: users, ownership, albums, asset identifiers, metadata, and processing relationships. Either side alone is incomplete when the goal is to restore the same household service rather than merely recover loose files.
The ZimaSpace Immich backup guide explains that comprehensive protection includes uploaded media and the database. That distinction provides a useful state definition: media answers what bytes exist, while database records answer how the application associates, presents, and controls those bytes.
Map the database and every original-media location to durable host or storage-system paths. Confirm that external libraries are protected by their own policy. Do not infer persistence from an internal container pathname; inspect the effective volume or bind mount that survives container deletion and recreation.
Configuration and Secrets Recreate the Service Boundary
Compose definitions, environment settings, storage mappings, proxy rules, and identity-provider configuration determine how services find data and one another. Passwords, signing material, and API credentials must also survive securely. Reconstructing files without these settings can leave the database reachable under the wrong identity or paths.
An Immich storage-planning analysis separates database and thumbnail placement from bulk original storage. Its lesson is architectural: one logical service can span several physical locations, so the persistence inventory must follow every mount and dependency rather than one project directory.
Store deployment definitions in version control after removing secrets. Keep secrets in an encrypted backup or secret manager with a documented restore path. Record ownership and permissions for bind mounts. During a drill, verify service-to-database access and media reads before exposing remote access or accepting new uploads.
Derived Data Is Rebuildable but Operationally Significant
Thumbnails, encoded videos, and some machine-learning outputs can be regenerated from authoritative inputs, depending on the version and retained records. Excluding them can shrink backups. The tradeoff is time, compute, heat, and reduced responsiveness while a restored server rebuilds a large family library.
An independent backup guide distinguishes must-have upload, library, and profile data from thumbnails and encoded video that Immich can regenerate. This does not make derivatives irrelevant; it gives operators a choice between backup size and the time required to regain fully prepared browsing and playback.
Measure a representative rebuild rate before excluding derived data. Multiply cautiously by the affected asset mix and include storage writes plus foreground contention. If the resulting delay violates the recovery objective, protect selected derivative paths or maintain spare compute capacity for the rebuild window.
Prove Persistence With a Container-Destruction Drill
Use a disposable clone of the deployment, never production. Record checksums for sample originals, a test album, two accounts with different access, and one known search. Remove only the cloned containers while retaining declared persistent storage, then recreate the stack from saved configuration and secrets.
A community persistence report describes Immich returning to onboarding after restarts because the intended host database directory remained empty. It is a cautionary example of why a configured path is not proof that writes reach it; observable state must survive the actual lifecycle operation being claimed.
Pass the drill only when both accounts return, album membership matches, original checksums agree, and the known search behaves as expected or enters a documented rebuild state. Any unexplained reset identifies missing persistence. Update the state map before relying on backup automation built from the same assumptions.
Recommended products
Tech & AI HUB
More to Read
How Does Immich Handle Authentication Across Local and Remote Sessions?
Immich uses server-side identity with client sessions, while proxy headers, origins, and OIDC redirects can make local and remote behavior differ.
What Causes Immich Search or Query Results to Slow as Data Grows?
Immich growth can enlarge indexes, evict hot pages, complicate filters, and delay media delivery; separate these stages before tuning.
Why Does Immich Behave Differently After a Container Restart?
After an Immich restart, transient cache loss is expected; lasting login, database, or media changes point to dependency or persistence faults.
