Immich: search your photos with AI locale

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.
#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.
- 01Image indexingFor 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.
- 02Query encodingWhen you type a phrase, the same model's text encoder turns it into a vector as well.
- 03ComparaisonImmich 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
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:
#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.
- 01Open the machine learning settingsIn 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).
- 02Choose the CLIP modelIn 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.
- 03SaveThe 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.
- 04Rerun indexing on the entire photo libraryIn 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.
- 05Test with a few known queriesPick 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.
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.
#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.
#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.
#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/.
#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.
Feedback, an error, or a clarification? Let us know—it improves the guide for everyone.