Immich ships with two machine learning features that transform how you find photos: Smart Search and Facial Recognition. Both are enabled by default and, once your library has been scanned, they work silently in the background on every new upload. If you have just installed Immich or are returning to a library that was never processed, this guide walks you through enabling, running, and tuning those features — including what to do if your hardware is under-powered.
How Machine Learning Works in Immich
All machine learning processing runs inside a dedicated Docker container called immich-machine-learning, separate from the main Immich server. This separation means you can run the ML container on a different, more powerful machine if your primary server lacks the resources — more on that later. The two features it powers are:
- Smart Search (CLIP) — indexes the visual content of every photo so you can search using natural language. Queries like “sunset on a beach”, “child with birthday cake”, or “dog in garden” return relevant results without any manual tagging.
- Facial Recognition — automatically groups photos by the faces they contain. Once an initial scan is complete, you assign names to detected faces and Immich links every matching photo across your entire library.
Both features are active out of the box. Photos uploaded after installation are processed automatically. The only action required is triggering a scan on photos that existed before Immich’s ML container processed them.
Running the Initial Library Scan
If you have an existing library, navigate to Administration > Jobs in the Immich web interface. You will see separate job queues for Smart Search and Facial Recognition. Click Run All on each to queue every photo for processing.
On a large library — tens of thousands of photos — this scan can take several hours. That is completely normal. The jobs run in the background and Immich remains fully usable throughout. You can monitor progress on the Jobs page, where each queue shows how many assets are pending, active, and complete.
Once the Smart Search job finishes, the search bar in Immich switches from metadata-only lookups to full visual search. Once Facial Recognition completes, head to Explore > People to review the detected faces.
Assigning Names to Faces
The People view shows thumbnail clusters — each cluster represents a unique face Immich has identified across your library. Click any cluster to open it, then click the pencil icon to assign a name. From that point on, Immich links every photo containing that person and makes them searchable by name. You can merge duplicate clusters if the same person appears under two separate groups, which sometimes happens with significant changes in appearance or lighting.
Face data improves over time as more photos are added and more names are assigned. It does not send data externally — all processing happens on your server.
Hardware Acceleration
By default, the immich-machine-learning container uses the CPU. Smaller libraries process comfortably this way, but if you have 50,000 or more photos — or simply want faster job completion — GPU acceleration makes a significant difference. Immich supports several acceleration backends via alternative image tags in your docker-compose.yml.
NVIDIA (CUDA)
image: ghcr.io/immich-app/immich-machine-learning:release-cudaRequires the NVIDIA Container Toolkit installed on the host and the deploy section in your compose file granting access to the GPU.
AMD (ROCm)
image: ghcr.io/immich-app/immich-machine-learning:release-rocmFor AMD discrete GPUs on Linux with ROCm drivers installed.
Intel (OpenVINO)
image: ghcr.io/immich-app/immich-machine-learning:release-openvinoWorks with Intel integrated graphics, including the iGPUs found in most Intel NUCs. A practical choice if you are running Immich on a NUC or a mini PC with no discrete GPU.
ARM NN
image: ghcr.io/immich-app/immich-machine-learning:release-armnnFor ARM-based devices such as Raspberry Pi or similar single-board computers running a supported ARM NN backend.
After changing the image tag, bring the container down and back up to pull the new image:
docker compose pull immich-machine-learning
docker compose up -d immich-machine-learningRunning ML on a Separate Machine
If your primary Immich server is under-powered — low RAM, no GPU, a fanless mini PC — you can move the immich-machine-learning container to a separate, more capable machine on your network. Deploy only that container on the second machine, then point your main Immich instance at it via the IMMICH_MACHINE_LEARNING_URL environment variable in your .env file:
IMMICH_MACHINE_LEARNING_URL=http://192.168.1.x:3003The main server handles all storage and the web interface; the remote machine handles inference. Keyword search — file names, dates, metadata — continues to work on the main server regardless.
Disabling Machine Learning on Low-RAM Hardware
If you cannot spare the RAM for the ML container and do not need Smart Search or Facial Recognition, you can remove it entirely. Open your docker-compose.yml and comment out or delete the immich-machine-learning service block:
# immich-machine-learning:
# container_name: immich_machine_learning
# image: ghcr.io/immich-app/immich-machine-learning:release
# ...Then disable the features in the web interface so Immich stops attempting to reach the container. Go to Administration > Machine Learning Settings and turn off both Smart Search and Face Detection. Save the settings, then apply the compose change:
docker compose up -dKeyword search continues to work without the ML container. Only visual and face-based queries are affected.
Keeping ML Features Up to Date
The CLIP model and face recognition model are bundled with the machine-learning image. When you update Immich by pulling new images, the models update automatically — no separate download step is needed. After a major model update, Immich may re-queue your library for re-indexing, which is expected behaviour.
If you notice Smart Search returning poor results after an update, trigger a fresh run from Administration > Jobs > Smart Search > Run All. The same applies to face detection if clustering looks less accurate than before.
Related Immich Guides
- Immich: The Complete Self-Hosted Google Photos Alternative
- What Is Immich? The Self-Hosted Google Photos Alternative
- How to Install Immich with Docker Compose
- Immich vs Google Photos: Is Self-Hosting Worth It?
- How to Set Up Immich Mobile Backup on iPhone and Android
- How to Run Immich on Proxmox: LXC Container Setup
- How to Put Immich Behind a Reverse Proxy with SSL
- Immich Hardware Requirements: Raspberry Pi, NUC, or NAS?
- How to Back Up Immich: Protecting Your Photo Library
- Immich vs PhotoPrism vs Piwigo: Best Self-Hosted Photo App?
