Skip to main content

Upgrading

Docker​

docker compose pull
docker compose up -d

That's it. The container image includes all dependencies.

uv tool upgrade immich-memories

pip​

pip install --upgrade immich-memories

Before upgrading​

Read the GitHub release notes before upgrading (the CHANGELOG.md in the repo is a stub that points there). Look for:

  • Breaking changes: config fields that were renamed or removed
  • New defaults: behavior changes that might affect your output
  • New dependencies: system-level requirements (FFmpeg version, etc.)

Upgrading Immich from v2 to v3​

Immich Memories supports Immich v2 and v3 — see Immich API compatibility for what that covers and what is actually tested. Keep the default automatic runtime policy during the server upgrade:

immich:
  api_version: auto  # auto | v2 | v3

You do not need to switch this setting for each run. On the next client start, auto detects the server major and uses its API contract. Explicit v2 and v3 are manual troubleshooting escape hatches for unusual proxies or deployments that prevent correct detection; they force the selected contract. They are the escape hatch if detection is wrong, not an upgrade ritual.

The client handles the three v3 wire changes that affect generation:

  • Duration: v2 duration strings and v3 integer milliseconds are normalized to seconds.
  • Upload: v2 keeps the device identity fields; v3 sends filename and omits the removed deviceAssetId and deviceId fields. The schema is selected before bytes are uploaded.
  • Search dates: date bounds include a UTC offset, which v3 requires.

After upgrading Immich, run:

immich-memories config test

This is a read-only authentication and compatibility check. It does not search assets, generate a video, create an album, or upload anything. A successful result includes the resolved v2 or v3 contract.

Config compatibility​

There is no automatic config migration, and a removed field will not tell you it is gone: unknown keys inside a known section are silently ignored, so a renamed field simply stops doing anything. (Unknown top-level keys and invalid values do fail at startup.) Renames are documented in the release notes — check them when a setting seems to have stopped taking effect.

In practice, most config fields have been stable since v0.1. Breaking config changes are rare and always called out in the release notes.

Data compatibility​

Analysis cache (cache.db): forward-compatible. The SQLite database has schema migrations that run automatically on startup. Upgrading never loses your analysis scores.

Video cache (downloaded clips): can be cleared safely at any time. If a new version changes the download format or caching structure, the old cache files are still valid but you can clear them without loss by deleting ~/.immich-memories/cache/video-cache (or via the UI Cache page).

Generated videos: output MP4 files are standalone. They don't depend on any version of Immich Memories.

Rollback​

If something goes wrong:

Docker: edit the image: line in your compose file to a specific tag (all tags: GitHub releases), then pull and recreate:

image: ghcr.io/sam-dumont/immich-video-memory-generator:0.59.2   # image tags have no `v` prefix
docker compose pull
docker compose up -d

uv/pip:

uv tool install immich-memories==0.59.2
# or
pip install immich-memories==0.59.2

Your analysis cache and config are preserved across version changes. The only thing that might need attention is config field names if the version you're rolling back to used different names.