Immich Machine Learning: Setup and Troubleshooting

We earn commissions when you shop through the links below. Learn more

Guide · Immich

Pinned version: Immich v3.3.5 (GitHub release). Last checked: 2026-10-28.

Immich's machine learning runs in its own container, immich-machine-learning, which the server reaches at http://immich-machine-learning:3003 by default. It powers Smart Search (CLIP) and face detection. You can run it on the CPU, speed it up with a supported GPU or NPU, move it to a more powerful computer, or switch it off on low-RAM machines.

All facts below come from Immich's official docs (checked 2026-10-28).

What the container does

Smart Search: Immich uses CLIP models to turn each image and each text search into an "embedding" and compares them. No visible tags or labels are created (FAQ).
Face detection: it finds faces. Facial recognition (grouping faces into people) then uses those saved results and runs between the server and the database.
Model downloads: models are downloaded into the /cache folder (MACHINE_LEARNING_CACHE_FOLDER), which is the model-cache volume in the standard compose file.
Idle unload: a model is unloaded after 300 seconds without use (MACHINE_LEARNING_MODEL_TTL) (environment variables).

Hardware it needs

Immich's requirements list a 6 GB RAM minimum (8 GB recommended) and 2 CPU cores minimum (4 recommended). On systems with only 4 GB of RAM, run Immich with machine learning switched off. Since v3, the machine learning container on amd64 needs a CPU at the x86-64-v2 level or newer. If you run Immich in a VM, pick a CPU type that exposes it. For sizing a box, see Immich hardware requirements and the hardware sizing tool.

Hardware acceleration (GPU or NPU)

The docs list these supported backends (Hardware-Accelerated Machine Learning):

Backend	Hardware	Notes from the docs
CUDA	NVIDIA GPUs, compute capability 5.2+	Official driver ≥ 545; NVIDIA Container Toolkit on Linux. "CUDA is the most reliable."
OpenVINO	Intel GPUs such as Iris Xe and Arc	Integrated GPUs are more likely to have issues; expect higher RAM use than CPU
ROCm	AMD GPUs	Image needs at least 35 GiB of free disk space
ARM NN	Arm devices with Mali GPUs	Needs `/dev/mali0` and the vendor's `libmali.so`
RKNN	Rockchip RK3566, RK3568, RK3576, RK3588	RKNPU driver 0.9.8 or later

Only Linux and Windows (via WSL2) servers are supported, and the instructions assume Docker Compose. The feature is still marked experimental.

Setup, per the docs:

Download the latest hwaccel.ml.yml into the same folder as docker-compose.yml.
Under immich-machine-learning, add the backend to the image tag, for example ${IMMICH_VERSION:-release}-openvino.
Uncomment the extends section and change cpu to your backend (openvino, cuda, rocm, armnn or rknn).
Redeploy the machine learning container.

You don't need to re-run existing jobs: the accelerator is used for jobs that run after you enable it. Platforms that don't support multiple compose files, such as Unraid and Portainer, can inline the matching block from hwaccel.ml.yml into the service instead.

Check that it works: watch the device with nvtop or intel_gpu_top, or check the container logs when a Smart Search job runs. You should see Available ORT providers listing your provider (for example CUDAExecutionProvider).

Run machine learning on another computer

To take load off a small server such as a Raspberry Pi, run only the machine learning container on a stronger machine (Remote Machine Learning):

On the remote machine, run the immich-machine-learning service from the docs' compose file, publishing port 3003. Use the same Immich version as your server.
In Immich, open Administration → Settings → Machine Learning Settings, click Add URL and enter http://<remote-ip>:3003.

Add the URL rather than replacing the default one. Immich then falls back to the local container when the remote one is down. URLs are tried in order, with no load balancing.

The docs point out that image previews are sent to the remote container, and the container "has no security measures whatsoever". Keep it on your LAN or a private network such as Tailscale, never on the public internet.

Common problems and documented fixes

Symptom	Documented fix
Errors about corrupt models or failed downloads	Delete the model cache volume so models download again, or download them manually from Immich's Hugging Face page into the cache folder
Worker crash with SIGKILL or code 137	Out of memory: add RAM or move machine learning to a machine with more RAM
Worker crash with SIGILL or code 132	The CPU isn't compatible (see the x86-64-v2 note above)
Log says a worker is exiting	Normal: models unload when idle to save RAM
High CPU during first import	Lower job concurrency to 1, or switch facial recognition to `buffalo_s` (then re-run Face Detection)
Running as non-root and models won't save	The user needs read/write access to `/cache`
Remote container was down, jobs failed	In Administration → Jobs, click Missing next to Smart Search and Face Detection

Switching machine learning off

Under Administration → Settings → Machine Learning Settings, you can switch it off completely or per model type. To stop the container from starting at all, comment out the immich-machine-learning service in docker-compose.yml. Search and the Explore page get much worse without it.

Sources

Immich docs, Hardware-Accelerated Machine Learning: https://docs.immich.app/features/ml-hardware-acceleration (checked 2026-10-28)
Immich docs, Remote Machine Learning: https://docs.immich.app/guides/remote-machine-learning (checked 2026-10-28)
Immich docs, Environment Variables: https://docs.immich.app/install/environment-variables (checked 2026-10-28)
Immich docs, Requirements: https://docs.immich.app/install/requirements (checked 2026-10-28)
Immich docs, FAQ (Machine Learning and Performance): https://docs.immich.app/FAQ (checked 2026-10-28)
Immich v3.3.5 release: https://github.com/immich-app/immich/releases/tag/v3.3.5 (checked 2026-10-28)