Immich AI Photo Search: How CLIP, Faces, and Filters Work
Immich AI photo search helps people find images in a personal library without remembering filenames or manually tagging every scene. It combines contextual matching with conventional metadata, recognized people, and text found inside images. This explainer describes how those paths differ, what the machine-learning service contributes, and how to enable and verify search in an existing Immich deployment. The result is useful, but it is not a guarantee that a model will understand every query or that a self-hosted installation has no privacy or operational trade-offs.
Why Immich AI Photo Search Is Getting Attention
Photo libraries grow faster than people can organize them. A phone may upload thousands of images over several years, while filenames such as IMG_2048.jpg say little about what a picture contains. Manual albums and tags work for a few memorable events, but become an incomplete index at larger scale.
Immich brings search into software that people can operate on their own server. Its contextual search can match a natural-language description to visual content, while its other search tools can filter by dates, places, people, albums, tags, and text. That combination appeals to home-lab operators who want retrieval that is more expressive than a folder tree, without treating an external cloud photo service as the only option.
What Is Immich AI Photo Search?
Immich is an open-source photo and video management application. Its search feature is not one single AI model: it is a collection of indexes and filters that answer different kinds of questions.
The contextual, or Smart Search, path uses models from the CLIP family to find photos and videos that are visually related to a text query. A query such as “a red canoe on a lake” can return a scene even when those words are not in the filename or embedded metadata. Separate features match recognized faces, read text with optical character recognition (OCR), or filter structured asset information such as location, capture date, and camera.
The Immich searching documentation describes the current search categories and model settings. The available features and configuration labels can change between releases, so the version-matched documentation in an installation is the reference for its exact behavior.
The Problem It Solves
Traditional file search compares text fields. It can find a photo named canoe-trip.jpg, or an image whose metadata includes a location, but it cannot infer that an unnamed photograph depicts a canoe. Users compensate by creating folders and tags, which is time-consuming and depends on consistent descriptions.
AI-based retrieval offers another signal: the content visible in the image. A person can search with a short description instead of first predicting the label chosen by a classifier. This is especially useful for approximate recall—finding “a dog on a snowy path,” for example—when no one recorded those words at upload time.
Visual similarity does not replace the rest of a library’s organization. A query about when a photo was taken is better answered by a date filter; finding an existing person is a face-search task; and a picture of a sign may be easier to find with OCR. Combining these methods avoids asking one probabilistic model to act as a perfect database.
How the Search Architecture Works
At a high level, Immich turns uploaded media into several kinds of searchable data. Original assets remain files in the library; database records hold asset information and relationships; background jobs analyze media; and search requests use the relevant index or filter. The current Immich documentation identifies PostgreSQL as the search database and VectorChord as the extension used for contextual CLIP search.
For contextual search, a machine-learning model represents visual content and text queries in a shared feature space. During indexing, the model processes assets and the system stores representations for later retrieval. At query time, it processes the text and compares that representation to indexed assets, ranking likely matches. The foundational CLIP research paper describes learning visual concepts from natural-language supervision. Immich’s exact model choices and implementation details are release-dependent; the practical point is that this is similarity ranking, not a literal keyword lookup.
Other search paths use different signals. Face recognition groups detected faces so a person can be selected; OCR reads visible text; metadata and filters operate on structured values. Standards such as the IPTC Photo Metadata Standard describe interoperable descriptive fields for images, but those fields are distinct from AI-generated visual representations.
| Search path | What it uses | Best for | Important limitation |
|---|---|---|---|
| Metadata and filters | Dates, places, filenames, folders, camera details, tags, and other asset fields | Exact attributes or known time and location ranges | Cannot infer an unrecorded visual description |
| Contextual Smart Search | CLIP-based representations of media and text queries | Approximate searches for scenes, objects, or visual concepts | Results are ranked guesses; wording and model choice affect relevance |
| People and faces | Face detection, recognition, and user-selected person groups | Finding images containing a known person | Similar faces, occlusion, and detection errors can confuse results |
| OCR | Text detected within an image | Signs, labels, screenshots, and other visible words | Small, blurred, stylized, or obscured text may not be recognized |
The separation matters operationally. Smart Search indexing and face processing are background machine-learning jobs; metadata filtering depends on imported or extracted fields. A library can therefore have working date filters while contextual search is still indexing, or have an image with OCR text that is not relevant to a visual query.
Components and Key Concepts
Machine-learning service. Immich runs supported models through its machine-learning component. It performs the processing needed for features such as contextual search and facial recognition. CPU and compatible accelerator support vary by deployment and model. Faster hardware can shorten indexing, but it does not automatically improve search quality.
Background jobs. New uploads and existing library items need analysis before all AI features can return useful results. Large backlogs consume CPU, memory, storage I/O, and time. A quiet queue does not necessarily indicate a failure; it may mean processing has completed or is paused.
Search database. Immich documents PostgreSQL with VectorChord for contextual search. This is why the database is part of both the application state and the search system. Protect it along with original files; deleting or replacing it can lose application records and require re-indexing.
Models and trade-offs. The administration settings expose available Smart Search model choices. Larger or more capable options may provide better ranking for some queries, but can use more memory and take longer during indexing and search. Language support also matters: select a model suitable for the language people actually use to describe their photos.
Privacy boundary. Self-hosting gives the operator control over where services run, but it is not synonymous with “no data leaves the server.” Check whether the machine-learning service runs on the same host or a separate host, how clients reach Immich, and whether proxies or other integrations forward data elsewhere. Face groups and photo contents are sensitive personal data; restrict accounts, remote access, and backups accordingly.
Real-World Use Cases
- Recall from a vague memory: Search for a scene such as “campfire near a tent” when the date and album are unknown.
- Find a person across events: Use the people view for an existing face group, then narrow by date or album.
- Retrieve a screenshot or sign: Use OCR or text-oriented search for words visible inside the image rather than relying on CLIP alone.
- Audit an archive: Combine a place, date range, camera, or folder filter with contextual results to narrow a large collection.
- Keep an independently operated library: Use search on a self-hosted system without making manual labels the only retrieval method. Immich still needs storage, database, update, and backup operations; the self-hosting architecture guide covers those responsibilities.
Getting Started and Verifying Search
Begin with a working Immich installation and a small set of representative photos. Confirm that originals and the database are backed up before changing machine-learning settings or rebuilding an index. Use the deployment’s current Compose file and release documentation rather than replacing services with an old example.
- Sign in with an administrator account and open Administration → Settings → Machine Learning Settings → Smart Search. Review the enabled state and available model choices for the installed release.
- Select a model that fits the host’s memory, accelerator support, and query language. Changing models can require assets to be indexed again; check the current documentation before starting a large reprocessing job.
- Check the job queue and allow Smart Search processing to finish for a representative subset. Avoid judging relevance on assets that have not been indexed.
- Search for a few concrete descriptions, such as “a red car in snow,” then compare results with metadata, people, and OCR queries. Try both a broad phrase and a more specific one.
- If indexing appears stalled, inspect the Compose project and its recent logs:
docker compose ps
docker compose logs --tail=100These commands show container state and recent service output without assuming a service name that may differ in a customized deployment. Look for repeated model-download errors, out-of-memory exits, database connectivity problems, or jobs that remain queued. Confirm the machine-learning component can reach the database and that the host has enough free memory and disk space. Use the service names and troubleshooting steps in the documentation for the exact Immich release.
Do not expose internal database or machine-learning ports publicly just to make search work. If processing is hosted on another machine, keep that connection on a trusted network and protect it with the deployment’s supported controls. For libraries with many assets, estimate the time and resource cost before re-running all jobs; normal search requests are not the same workload as a full first-time index.
Common Misconceptions
“Smart Search is a tag generator.”
Contextual search can retrieve an image without writing a descriptive tag into its metadata. A similarity representation is useful for ranking but is not a human-readable, guaranteed list of objects. Use explicit tags or descriptions when those labels need to be reviewed, exported, or shared with other software.
“If a phrase returns no photos, the photos are not in the library.”
The relevant assets may not be indexed, the model may not understand the wording, or the concept may be visually ambiguous. Try a simpler phrase, check processing status, and use dates, locations, people, OCR, or filenames as independent paths.
“Running Immich locally makes every AI result private by default.”
Where a model runs depends on how the services are deployed and configured. Local processing can keep inference within infrastructure you control, but remote hosts, public endpoints, proxies, logs, user access, and backups remain part of the privacy boundary.
Related Articles
- Immich Self-Hosting: Architecture, Setup, and Backups explains deployment, storage, machine learning, and recovery.
- Automated Photo Tagging System Architecture covers the broader pipeline for machine-generated image labels.
- Photo Metadata Standards and Management explains descriptive fields that differ from contextual search.
- Edge AI Computing explores the trade-offs of processing models near the data.
Changelog
- 2026-09-26: Published the initial explainer.
