Immich Machine Learning V2: 5 Fixes That Work

 

If you updated Immich this month and suddenly smart search returns garbage, face recognition stopped detecting people, or the machine-learning container keeps crashing, you are not alone. The October 2026 Immich update introduced Machine Learning V2 — a new optimized model format that uses less RAM and runs faster — but it does not switch on by itself. You have to opt in with one environment variable, and skipping that step (or switching models the wrong way) is behind almost every broken-ML report since the update.

This guide walks you through 5 fixes that actually work: the one-line V2 opt-in, the correct redeploy sequence, how to repair search results after a model change, the exit 137 out-of-memory crash, and the ML settings most people never tune. Everything below was verified against Immich's official docs and the current release notes.

What Is Immich Machine Learning V2?

Immich ships its AI features — smart search ("show me beach photos"), facial recognition, and object detection — in a separate immich-machine-learning container. With the October 2026 update, Immich released a V2 model revision: the same models in a new optimized format that consumes noticeably less RAM and system resources.

Why does this matter? On resource-constrained homelab hardware — a low-power NAS, a mini PC, a Raspberry Pi-class box — the old ML models were often the single hungriest container in the stack. V2 makes full AI capabilities far more forgiving on that hardware. But there is a catch: V2 is opt-in. Updating the Immich images alone does not enable it. You must add the environment variable MACHINE_LEARNING_MODEL_REVISION=v2 to the machine-learning service yourself.

⚠️ Symptoms you have the problem: smart search returns irrelevant results after updating, face recognition misses obvious faces, the immich-machine-learning container restarts in a loop, or jobs pile up in the failed queue under Administration → Jobs.

Fix 1: Add the MACHINE_LEARNING_MODEL_REVISION=v2 Variable (The Core Fix)

This is the fix most people need. Add the variable to the immich-machine-learning service — not the server, not the database.

Option A: Plain docker-compose.yml

Open your compose file and add one line under the machine-learning service's environment section:

services:
  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/machine-learning:${IMMICH_VERSION:-release}
    environment:
      - MACHINE_LEARNING_MODEL_REVISION=v2
    volumes:
      - model-cache:/cache
    restart: always

If your compose file uses mapping syntax instead of list syntax, write it as MACHINE_LEARNING_MODEL_REVISION: v2 — both forms work.

Option B: Portainer

Left sidebar → Stacks → click your immich stack → Editor tab. Find the immich-machine-learning: service, add - MACHINE_LEARNING_MODEL_REVISION=v2 under its environment block, then click Update the stack.

Option C: Dockhand

Left sidebar → Stacks → click the immich instance. Add the variable to the immich-machine-learning service, then click Save and Redeploy.

Fix 2: Redeploy Cleanly and Verify the ML Container Is Healthy

Editing the file is not enough — the container must be recreated so it picks up the new variable. From the folder containing your compose file:

docker compose up -d
docker ps --filter "name=immich_machine_learning" --format "table {{.Names}}\t{{.Status}}"

The status should show Up and stay up. Then confirm the container actually loaded the V2 models:

docker logs immich_machine_learning --tail 40 | grep -i "model"

Look for lines showing models loading from the cache in the new format. If the container keeps restarting, skip to Fix 4 — you likely have a memory problem, not a config problem.

Fix 3: Re-Run Smart Search Indexing After the Model Change

This is the step almost everyone misses, and it is why "search worked before the update and is broken now" is the most common complaint. Your photo library was indexed with the old model. Old and new embeddings do not mix — after the switch, search queries compare new-model vectors against old-model vectors and return nonsense.

The fix: re-index everything with the new model.

1. In the Immich web UI, go to Administration → Jobs.
2. Find Smart Search (and Face Detection if you use it).
3. Click the ⋯ menu and choose to run All — not just missing.
4. Wait until the queue drains completely. On a large library this can take hours; that is normal.

✅ Rule of thumb: every time you change a CLIP or facial-recognition model in Immich, run a full re-index. A partial index after a model change is worse than no index — it silently returns wrong results.

Fix 4: Stop the Exit 137 Crash (Out of Memory)

If docker ps shows the ML container restarting and docker logs ends with exit 137, the container was killed for using too much memory. The V2 format helps, but a big model on a small box can still OOM — especially during the first re-index when everything runs at once.

You have two levers:

• Pick a smaller model. In Immich's ML settings, switch the CLIP model to a smaller variant (for example, a base-size model instead of large). Smaller models use far less RAM at a modest accuracy cost.
• Give the box more headroom. Stop other heavy containers during the initial re-index, or add RAM if the machine is consistently near its limit. The XLM-class models genuinely want around 2 GB for the ML container alone.

Do not "fix" this by setting an absurd memory limit in compose — the OOM killer will just strike sooner and corrupt an in-progress index.

Fix 5: Tune the ML Settings Nobody Touches

Two settings in Immich's machine-learning configuration deserve a look after the V2 switch:

• MACHINE_LEARNING_MODEL_TTL — how long models stay loaded in memory when idle. If GPU power draw stays high after inference finishes, the model is sitting loaded; the default TTL unloads it after a few minutes of idleness. Lower it on shared hardware.
• MACHINE_LEARNING_WORKERS — concurrency for inference. On a single GPU, keep this at 1: more workers multiply VRAM usage and are the classic cause of mysterious ML crashes on small cards.

If you run the ML container on a separate GPU box over the LAN (via IMMICH_MACHINE_LEARNING_URL), make sure the server and ML image tags match and the box is on the same L2 network — a sleeping GPU host leaves jobs stuck in the failed queue with no CPU fallback.

When It Is Not the ML Container

If the entire Immich stack refuses to come up after your changes — not just the ML service — the problem is probably container networking rather than machine learning. We covered that class of failure in our Nginx 502 Bad Gateway in Docker fix guide, which walks through diagnosing containers that cannot reach each other.

FAQ

Do I have to switch to Machine Learning V2?

No — the old models keep working. But V2 uses less RAM and runs faster, which matters most on memory-constrained homelab hardware.

Will I lose my existing face recognition data?

No, your named people and albums are preserved. But you must re-run the Smart Search and Face Detection jobs (Fix 3) so embeddings are regenerated with the new model format.

Why is smart search worse right after the update?

Mixed old/new model embeddings. The library was indexed with the old model; queries now use the new one. A full re-index under Administration → Jobs fixes it.

How do I know the ML container is healthy?

docker ps should show it Up for longer than a few minutes, and docker logs immich_machine_learning --tail 40 should show models loading without error lines or restarts.