Intermediate 12 minDaily plan

Immich: search your photos with AI locale

Sheets of paper are spread out beside a laptop on a wooden desk.

Immich, the self-hosted alternative to Google Photos, lets you find a photo by typing a description ("dog on the beach," "birthday cake") instead of a filename. This AI photo search relies on a CLIP model that runs on your server, in Immich's machine learning container. This guide explains how it works, how to choose a multilingual model to search in French, which errors to watch for, and what actually leaves your network. The procedure described follows the official documentation; it was not re-run on a test instance for this guide.

By Mohamed Meguedmi·Update 2026-11-21·Tested on Windows, macOS, and Linux

#AI photo search in Immich: how it works

The feature is called Smart Search in Immich's documentation ("smart search" or context search in the interface). It doesn't read your photos on the fly at query time. It relies on two separate operations, both handled by the immich-machine-learning service.

  1. 01
    Image indexing
    For each photo, the CLIP model's image encoder computes a numeric vector (an embedding) that summarizes its visual content. This vector is stored in Immich's database. This is the job of the "Smart Search" task shown in the admin panel; on a large photo library, it can take a long time.
  2. 02
    Query encoding
    When you type a phrase, the same model's text encoder turns it into a vector as well.
  3. 03
    Comparaison
    Immich returns the photos whose vectors are closest to your phrase's vector. There's no text generation and no "understanding" in the chatbot sense: it's a similarity search in a shared image-text space.

The direct consequence: text and images must have been encoded by the same model. If you switch models, all photos must be reindexed; otherwise, old and new vectors are no longer comparable.

#CLIP is not a vision assistant

The complete kit for building your own AI assistant.

Benefit from our experience and a guided path to build your local assistant and use your AI every day.

  • Lifetime online access
  • PDF + files
  • Refunded within 30 days

People often confuse Immich's CLIP search with the "vision" models you run with Ollama (Qwen3-VL, Gemma, etc.). They're two different tools that meet two different needs.

What CLIP does in Immich
Rank your photos by how closely they match a sentence. The result is a sorted list of images, not a written answer. The model is small and indexing happens once; after that, search is fast.
What a vision assistant does
Describe an image, answer a question about its content, read text (OCR), compare two images. It generates text, one image at a time, and costs far more in compute and memory.
What CLIP can't do
Answering "how many people are in this photo?", describing a scene, reliably reading a photographed document, or counting. It gives a similarity score, nothing more.
What Immich doesn't include natively
A vision LLM that would write captions or chat with your photo library. Third-party projects exist, but they aren't part of Immich and aren't covered here.

If what you need is to find "the photo of Tuesday's whiteboard," CLIP is often enough. If you need to extract the text from that whiteboard or summarize it, you need a vision model, for example via Ollama, on an image you explicitly send to it.

#Prerequisites

A working Immich instance
Installed with the official docker-compose.yml, which includes the immich-machine-learning service. If you removed it from your compose file, smart search won't work.
An administrator account
You choose the model and launch indexing tasks in the server admin panel.
Memory and time
A larger CLIP model requires more RAM and indexes more slowly. We don't publish timing figures: they depend on the model, the number of photos, and the CPU or GPU, and we have no documented measurements to give you.
Hardware acceleration (optional)
Immich documents machine learning acceleration (CUDA for NVIDIA, OpenVINO for Intel, ROCm for AMD, ARM NN and RKNN for certain ARM boards). It's not required: the CPU is enough, just slower.
A recent backup
Switching models doesn't touch your files, but rerunning heavy jobs on a home server is a good time to check that your database and originals backups are up to date.

To check that the machine learning service is running, from the folder that contains your docker-compose.yml:

Terminal — ML container status and logs
# Lister les services Immich et leur état
docker compose ps

# Suivre les journaux du service de machine learning
docker compose logs -f immich-machine-learning

#Enable AI photo search and choose a multilingual model

The default model listed in the Immich documentation is ViT-B-32__openai, a CLIP model trained mainly on English captions. It works, but a query in French generally returns less relevant results than the same query in English. The documentation recommends using a multilingual model if you search in a language other than English.

  1. 01
    Open the machine learning settings
    In Immich, open Administration, then Settings, then the Machine Learning section. Make sure machine learning is enabled and that the service URL points to your container (by default, the immich-machine-learning service in the compose file).
  2. 02
    Choose the CLIP model
    In the Smart Search subsection, replace the model name. The available models are published by the Immich team on Hugging Face, and the documentation links to a list showing each one's size, memory requirements, and whether it's multilingual. The multilingual families mentioned include nllb-clip (for example, nllb-clip-base-siglip__v1, nllb-clip-large-siglip__v1) and XLM-Roberta (for example, XLM-Roberta-Large-Vit-B-16Plus). Copy the exact name from the official list: a typo will prevent the download.
  3. 03
    Save
    The next time it's needed, the ML container downloads the model from Hugging Face and then keeps it in its cache (the model-cache volume in the official compose file). As a result, the first call may be slow, or may fail if the server has no Internet access.
  4. 04
    Rerun indexing on the entire photo library
    In Administration, open Jobs. On the Smart Search row, run the job on all photos ("All"), not just the missing ones ("Missing"): vectors computed with the old model are no longer compatible. Track progress on the same page and in the container logs.
  5. 05
    Test with a few known queries
    Pick three or four photos whose content you know, search for them in French, and check that they show up. That's your only real test: relevance depends on your photo library, and we can't guarantee it for you remotely.
!
Until reindexing is finished, results are inconsistent
During processing, some photos have vectors from the new model and others from the old one. Results may seem poor or incomplete. Wait for the Smart Search task to finish before judging a model.

Which model should you choose? The documentation doesn't name a universal "best" model. It's the classic tradeoff: a bigger model (large variants) promises better relevance but uses more memory and indexes more slowly; a base model is lighter. On a small server or a NAS without a GPU, start with a multilingual base variant; if the relevance disappoints you and the machine has headroom, try a bigger variant, knowing you'll have to reindex everything.

i
Query language and NLLB models
The nllb-clip models rely on a multilingual text encoder that takes the query language into account. According to the documentation, Immich uses the language set in the interface for these models. So keep the interface in French if you search in French. This behavior may change from one version to the next: check the "Searching" page in the documentation for your version.

#Searching your photos in French

Once indexing is complete, you search from the search bar in the web or mobile app. Depending on the version, the interface offers several search types: context (CLIP search), file name, description, and in recent versions, OCR-recognized text. To search by description, stay in context mode.

Describe what's visible
"red bike against a wall," "sunset over the sea," "child blowing out candles." CLIP responds to objects, scenes, colors, and moods.
Avoid what the image doesn't show
"vacation 2019 at Paul's" doesn't match anything visible. For the date, location, or person, use the filters.
Combine with filters
The filter panel lets you narrow results by people (facial recognition, another feature of the same ML container), location, camera, dates, and media type. A short query plus two filters often beats a long sentence.
Reformulez
If "chat" returns too many results, be more specific: "chat noir endormi sur un canapé." If nothing comes up, simplify. Also try English: if English works noticeably better, your model is probably monolingual.
Don't confuse this with text search
Context mode doesn't read text in photos. To find a screenshot by its written content, use OCR search if your version offers it, or search by filename or description.

Results are sorted by similarity and there's no "match / no match" threshold: search always returns something, even for an absurd query. The top results are the closest; the further down you go, the less relevant they are.

#Privacy: what stays on your side

This is the main selling point of self-hosted AI photo search, but it's worth stating precisely. This guide describes the documented architecture; it is not an audit of your installation and doesn't guarantee that no data leaves your network.

Computation
In the official setup, photos and queries are encoded by the immich-machine-learning container, on your machine. The embeddings are stored in your PostgreSQL database.
Downloading the models
Model weights are downloaded from Hugging Face the first time they're used. This outbound traffic is normal; it doesn't contain your photos. Once the model is cached, it isn't downloaded again as long as you keep the volume.
A remote ML service
The machine learning service URL is configurable: you can run the ML container on another machine (a PC with a GPU, for example). In that case, your photos are sent to that machine. Keep it on your local network or behind a VPN, never exposed directly to the Internet.
Other features
Maps, version checks, or other settings may contact external services. They're independent of CLIP search; review the server settings if you're aiming to run with no outbound connections.
Disable
Machine learning, or just smart search, can be disabled in the settings. Your photos remain accessible; you only lose search by description.
→
Server without internet access
If your server is isolated, the model won't be able to download. One approach is to allow outbound access for the first download, then cut it off: the model stays in the cache volume. Then check the ML container logs to confirm it's loading the model from the cache.

#Common errors and troubleshooting

Search returns nothing or an error
The ML container is stopped or unreachable, or the URL in the settings is wrong. Check docker compose ps and the immich-machine-learning logs.
Model download fails
Misspelled model name, no access to Hugging Face, or a full disk. The ML container logs usually tell you which.
The ML container keeps restarting
Often insufficient memory with a large model, or an acceleration image (for example, -cuda) that doesn't match the hardware. Go back to a smaller model or the CPU image to isolate the problem.
Poor results after switching models
The Smart Search task was run only on missing photos, or it hasn't finished. Rerun it on all photos.
Poor results in French, decent in English
The active model is monolingual (for example, the default ViT-B-32__openai). Switch to a multilingual model and reindex.
New photos can't be found
Indexing of new files goes through the job queue. If it's paused or overloaded, recent photos don't have a vector yet. Check the jobs page.
Terminal — restart the ML service after a change
# Redémarrer uniquement le conteneur de machine learning
docker compose restart immich-machine-learning

# Afficher les 100 dernières lignes de journal
docker compose logs --tail=100 immich-machine-learning

#Limitations and sources

This guide doesn't publish any indexing times, measured memory usage, or relevance scores: we have no documented measurements (hardware, version, model, library size) to present. The ballpark figures you'll find online depend heavily on these parameters; the only reliable benchmark is a test on your own server, with a few queries whose answers you already know.

Immich moves fast. Menu labels, the list of available models, and search types change from one version to the next. The information above is based on the "Searching" page of the official documentation, consulted by our editorial team on October 30, 2026; it was not rechecked on the publication date. If anything differs, your version's documentation takes precedence: docs.immich.app/features/searching/.

i
CLIP search and RAG: same idea
CLIP search works like the "retrieval" part of a RAG pipeline: stored embeddings, an encoded query, a similarity comparison. The difference is that the model encodes both images and text into the same space. If you've already built a RAG pipeline over your documents, you have the right mental model.

#Go further

CLIP search finds photos; to describe them, ask questions about them, or extract text from them, you need a vision model. These guides on the site go further into the topic.

Local multimodal vision LLMs: analyze images with Ollama
The companion guide: describe an image, run OCR, and ask questions about a photo with a local vision model. The natural complement to CLIP search.
Qwen3-VL locally with Ollama
An accurate vision model for analyzing in detail the photos that Immich search helped you find.
BGE-M3: embeddings that speak French
The same multilingual embedding principle applied to text, to understand why a monolingual model penalizes queries in French.
Did this guide help you?

Feedback, an error, or a clarification? Let us know—it improves the guide for everyone.