Skip to main content

Upgrading

Read the release notes, back up the store, then upgrade. Keep the backup for rollback: a newer release can migrate the store to a revision older code will refuse.

API key permissions​

Existing keys with All permissions continue to work. Preflight now warns about their broad access; replace them with the documented read set, adding upload rights only when needed. Run immich-memories config test after changing a key.

Missing read permissions stop a cut before it starts. Missing upload or tagging permissions keep the completed film locally with a download option and a specific delivery message. Without asset.delete, previous versions remain in Immich. Partner keys need only read rights.

Docker​

Back up while the old release is still running:

docker compose exec immich-memories immich-memories store backup
docker compose cp immich-memories:/home/immich/.immich-memories/backups ./backups

Keep that backup and manifest. Download the new release's Compose assets and set IMMICH_MEMORIES_VERSION=X.Y.Z in .env, without the v prefix. That one value selects matching app, inference and standalone worker images; the CUDA file adds the inference CUDA suffix. Keep your chosen COMPOSE_FILE, credentials and saved Settings. If you use a single-file export, regenerate it with the new version and preserve its private settings key. Then upgrade:

docker compose pull
docker compose up -d
docker compose exec immich-memories immich-memories models fetch
docker compose exec immich-memories immich-memories preflight

Config and films survive a recreate. models fetch checks the new release's pins and downloads only changed files.

uv / pip​

immich-memories store backup
uv tool upgrade immich-memories
immich-memories models fetch
immich-memories preflight

For pip, keep the same extras:

pip install --upgrade "immich-memories[all]"

On Apple Silicon, use immich-memories[all-mac], or immich-memories[all-mac,auth] for OIDC.

Kubernetes and Terraform​

Back up, change the pinned image tag, apply, then run models fetch and preflight in the app container. The base init container skips fetching when its required paths are present, so changed pins need the explicit fetch. The generated GPU setup runs models fetch --detectors --laya whenever its model init container runs, verifying existing artifact digests. See Kubernetes upgrades or Terraform upgrades.

Upgrading Immich from v2 to v3​

Leave version detection on auto:

immich:
  api_version: auto

After upgrading Immich:

immich-memories config test

This read-only check prints the resolved v2/v3 contract. Overrides are for troubleshooting a proxy, not an upgrade step. Originals are unchanged.

Immich 3.3​

  • Country names. Immich 3.3 stores GeoNames' English country names ("The Netherlands", "Turkey", "Cabo Verde"). The app reads those and the earlier names alike, so titles and captions still translate the country.
  • Stacks. Add stack.read to the key if you want a stack (an edit and its original, a burst) to play as its top picture. It is optional: without it the run logs one warning per account and treats every stacked picture as its own candidate.
  • Native people sharing accepts 3.3.0-rc.1, later 3.3.0 release candidates and every 3.3 release. See A second Immich account.

Config compatibility​

Unknown fields inside a known section are ignored; invalid values or unknown top-level sections fail startup. A renamed setting can stop taking effect, so check the release notes. A removed key is dropped with a warning at startup that names it and says what to do, for example:

Ignoring config keys that no longer exist in config.yaml; delete them to silence this:
  audio.music_volume_db: nothing read it; remove it from your config
  defaults.output_orientation: the CLI picks the orientation; remove it from your config

Delete the key once you've read why.

The low-end tier is basic. A tier: nas in YAML, IMMICH_MEMORIES_TIER=nas, IMMICH_MEMORIES_DEPLOYMENT_TIER=nas or a saved Settings value of nas stops startup with tier 'nas' is now called 'basic': set tier: basic. Change the value to basic.

The reader only runs with advanced.llm.enabled: true. A config that sets advanced.llm.base_url, model or another reader field without it keeps the reader off: model titles, music mood and model selection stay off, startup logs a warning naming the fields it found (never their values), and preflight reports Reader configured but disabled. Add enabled: true under advanced.llm. See enabling a reader.

The store upgrades its schema when opened. Keep a backup and its manifest from before an update; if you roll back the app, restore the matching backup rather than downgrading a live schema. Keep the app, inference image and render worker on matching version tags.

Rollback​

Restore the backup taken before upgrading if the newer release migrated the store. Stop the app before restoring. Container restore uses a one-off process, not exec in the running app.

For Docker, use this order. The backup and its manifest must be together on the mounted config volume. Replace the example backup name with yours (.dump for PostgreSQL):

docker compose stop immich-memories
# Set image: to the old release in Compose (and its override, if present).
# Align inference and render worker tags with that release too.
docker compose pull
docker compose run --rm immich-memories immich-memories store restore \
  --from /home/immich/.immich-memories/backups/store-20260930T090000Z.db --force
docker compose up -d
docker compose exec immich-memories immich-memories preflight

Python:

uv tool install --force --python 3.12 "immich-memories[all]==X.Y.Z"

Kubernetes/Terraform: restore the old image tag and apply, then restore the old store backup with that release. Schema downgrades can drop tables and rows; the backup is the rollback.

Inspecting the store before an upgrade​

store status, store backup, config show and preflight read the existing schema without upgrading it, including saved settings. A revision mismatch reports the actual and expected schema. Back up first; ui, generate, auto and the explicit store migrate command upgrade the configured store before writing.