Immich Just Got a Lot Lighter: V2 Machine Learning Models Are Rolling Out to Homelabs

The hardest part of running a self-hosted Google Photos alternative on a NAS has never been storage. It is the machine learning. Facial recognition, smart search, and OCR chew through RAM and CPU cycles, and on a low-power box like a Synology, that has meant long job queues, sluggish searches, and fans that never quite settle down. Immich, the open-source photo backup platform the homelab world has largely standardized on, just shipped an answer: a re-export of its ML models, called V2, that the project's own notes describe as cutting memory and latency on every backend.

The catch, and the reason this story matters this week, is that V2 is opt-in. Mid-October NAS roundups, including the widely followed Marius Hosting mid-October 2026 update, are now telling self-hosters to add a single environment variable to their Immich machine-learning container: MACHINE_LEARNING_MODEL_REVISION=v2. Without it, your stack keeps running the older model exports. With it, the optimized format takes over.

What V2 actually changes

The details come from the Immich 3.3 release and the early adopters who have already flipped the switch in their homelab infrastructure repos. The V2 exports run fp16, that is 16-bit floating point, on GPU, with bucketed input shapes, instead of the fp32 precision the V1 exports used. Half the bit width per tensor means the models consume substantially less memory during inference, and the bucketed shapes reduce the per-request latency overhead.

Crucially, upstream reports that the V2 outputs are numerically equivalent to V1. The optimized models produce the same embeddings, the same face clusters, the same search results. That equivalence is why administrators do not need to rerun any existing machine learning jobs after enabling V2. Your library's face index and smart-search embeddings carry over untouched. The V2 models also download into a separate cache directory, so the old models remain on disk, and dropping the environment variable rolls everything back to V1.

The 3.3 release also widened the hardware story around the ML container. Support for Rockchip's RKNPU, the neural processor in many ARM-based boards and newer NAS units, now covers all models, including OCR. NVIDIA Ampere and newer GPUs get TensorRT RTX acceleration. If you have been running Immich on CPU-only hardware and eyeing an NPU-equipped board, the V2 release is the clearest signal yet that the project is serious about low-power accelerators.

The V2 exports run fp16 on GPU with bucketed input shapes, cutting memory and latency on every backend, while the outputs stay numerically equivalent.

Why this matters most for NAS boxes

Immich is heavyweight for a home server. The server, database, Redis, and machine-learning containers add up, and the ML container has historically been the hungriest of the four. On a Synology or UGREEN NAS with limited RAM, every optimization in the inference path translates directly into shorter smart-search job queues and a box that stays responsive while background processing runs.

That is exactly the framing in the mid-October roundup: the optimized V2 format consumes less RAM and system resources, which makes running Immich's full AI capabilities, face recognition, duplicate detection, smart search, OCR, far more forgiving on resource-constrained homelab hardware. For the growing cohort of users who run Immich as their family's primary photo store, replacing Google Photos or iCloud, this is the difference between a service that feels local and snappy and one that feels like a background batch job.

The cache gotcha, learned the hard way

Before you flip the switch, one real-world caution from the community. V2 writes prepared model graphs into the model cache on first load, which is part of how it achieves the lower latency. At least one homelab operator, documenting their fix on October 7, found their 4Gi model-cache volume run out of space during the V2 download, sending the machine-learning container into a crash loop with an out-of-space error. Their fix was to grow the cache to 16Gi and preload the exact CLIP model their config uses.

This is not a reason to skip V2. It is a reason to check your /cache volume before you redeploy. The V2 models download alongside, not on top of, the V1 models, since they live in a separate directory, so plan for the temporary extra space. If your Immich stack pins the cache to a small volume or a tmpfs mount, resize it first. And keep the rollback in mind: removing the environment variable and redeploying returns you to the cached V1 models, no drama.

Also in Immich 3.3

The ML optimization was not the only thing in the 3.3 release, and a few of the other changes deserve a mention for anyone running Immich as household infrastructure. OCR now uses the multilingual PP-OCRv6 family, with better text recognition accuracy and three sizes to match your hardware. OAuth integration improved: user roles, storage quotas, and preferred usernames now synchronize with an identity provider on every login, not just at registration.

Smaller fixes landed too. Album editors can now update album titles and descriptions, JFIF image support was added, map rendering for non-Latin text improved, and a long-standing bug with incorrect storage capacity reporting on macOS, particularly in some Docker configurations, was fixed. Alongside the bug fixes affecting mobile backups, facial recognition, video transcoding, and the web interface, 3.3 reads as a stability and performance release more than a feature splash. Which, for software that holds your family's photos, is exactly what you want.

How to enable V2 on your stack

The procedure is the same whether you manage Immich through Portainer, Dockhand, or a raw compose file, and it takes about a minute. In your Immich compose stack, find the immich-machine-learning service and add one environment variable:

MACHINE_LEARNING_MODEL_REVISION: v2

Then update or redeploy the stack. The ML container will download the V2 model exports into the cache on its first start. In Portainer that means Stacks, your Immich stack, Editor tab, then Update the stack. In Dockhand it is Stacks, the Immich instance, then Save and Redeploy. Give the container a few minutes to pull and prepare the models, and check the cache volume has room first, per the gotcha above.

Because V2 is reversible, there is no penalty for trying it on a test stack first.

The bigger picture

Immich's V2 rollout is a small, well-executed example of a trend that defines self-hosting in 2026. Open-source projects are no longer just matching cloud features years late. They are adopting the same serving optimizations, fp16 inference, prepared graphs, hardware accelerators, that the hyperscalers use, and packaging them as a one-line configuration change. The gap between a homelab and a data center was never the algorithms. It was the engineering around them. Every release like this one closes it a little further.