Search any photo folder from the command line by describing what's in it. Runs entirely on your laptop (currently only tested on MacOS)
Initially built for, and evaluated on, wildlife photography. Because it uses OpenCLIP models trained on about two billion image–text pairs from the web, it works just as well for any kind of photo: landscapes, cities, people, food, documents.
Imagine a week-long photography trip in Kenya. That's easily 10,000 photos a day. Back home you remember a very specific moment: the leopard yawning on a branch at dusk, two zebras crossing the river, a lion resting under a tree at sunset. But it's one frame among 70,000 files called DSC_4821.JPG, and scrolling through
thumbnails takes hours.
With wildsearch you index the trip folder once, then describe the moment you remember:
$ wildsearch search "a lion resting under a tree at sunset" -p ~/Pictures/Kenya2026The indexing takes some time, but only needs to be done once. After, the best matches come back in seconds. The same works for decades of family photos spread over old hard drives, where nobody remembers which folder anything is in.
Here is an example usage of the application. First, index the folder you want to search. Then you can search for specific pictures, e.g., "a lion resting under a tree at sunset". Status shows you what folders are currently indexed and you can decide to forget a specific folder, which deletes that folders index, or you can reset, which deletes all the indexes.
$ wildsearch index ~/Pictures/Kenya2026
~/Pictures/Kenya2026: 1,240 new, 0 changed, 0 removed
✓ Embedded 1,240 photos
$ wildsearch search "a lion resting under a tree at sunset" -p ~/Pictures/Kenya2026 -n 3 --open
# Score Photo
1 0.312 day3/IMG_0412.jpg
2 0.305 day3/IMG_0415.jpg
3 0.271 day1/IMG_0088.jpg
Searched all 1,240 photos in ~/Pictures/Kenya2026.
$ wildsearch status
Index: ~/Library/Application Support/wildsearch/index.db (2.6 MB)
Folder Photos Embedded Last indexed
~/Pictures/Kenya2026 1,240 1,240 2026-10-24 18:15
$ wildsearch forget ~/Pictures/Kenya2026
✓ ~/Pictures/Kenya2026: forgot 1,240 photos
$ wildsearch status
Nothing indexed yet. Run: wildsearch index FOLDERKeyword search (like Finder's) can find lion. wildsearch can find a lion resting under a tree at sunset, or an animal camouflaged in tall grass: any description, in plain language, without anyone having labelled the photos first.
wildsearch uses CLIP-style models (OpenCLIP), which map images and text into the same vector space: a photo and a sentence that describe the same thing end up close together. Searching is then a nearest-neighbour lookup.
wildsearch index: once per folder, then only new or changed photos.
flowchart LR
A[Photo folder] --> B[Scan<br/>path, size, mtime]
B --> C{New or<br/>changed?}
C -- yes --> D[Decode + resize<br/>in batches of 32]
D --> E[CLIP<br/>image encoder]
E --> F[(SQLite index<br/>one 512-d vector<br/>per photo)]
C -- no: skip --> F
wildsearch search
flowchart LR
Q["'a lion resting<br/>under a tree'"] --> T[CLIP<br/>text encoder]
T --> R[Cosine similarity<br/>against all vectors]
F[(SQLite index)] --> R
R --> S[Top N photos]
- Indexing embeds each photo once and stores its vector (2 KB) in a local SQLite file.
Re-running
indexonly processes new or changed photos, and an interrupted run resumes. This only takes time the first time. where it stopped: progress is committed after every batch. - Searching never opens a photo. It embeds the query and compares it with all stored vectors in one matrix multiplication, which takes milliseconds even for tens of thousands of photos.
Requires Python 3.12+ and uv
$ git clone https://github.com/EonP/wildsearch && cd wildsearch
$ uv tool install --editable ".[ml]"This puts a wildsearch command on your PATH. The model weights (~350 MB) are downloaded
on first use and cached; after that everything runs offline.
| Command | What it does |
|---|---|
wildsearch index FOLDER… |
Embed new and changed photos, forget deleted ones |
wildsearch search "QUERY" [-p FOLDER] [-n 10] [--open] |
Best matches; -p defaults to the current folder, --open shows them in Preview |
wildsearch status |
Indexed folders, photo counts, database size |
wildsearch forget FOLDER… |
Remove folders from the index |
wildsearch reset |
Delete the whole index |
Photo files are never modified. The index lives in your user data folder
(~/Library/Application Support/wildsearch/index.db on macOS); use --db or
WILDSEARCH_DB environment variable to put it elsewhere.
Measured stage by stage on two folders at opposite ends: 11,788 small photos from CUB-200-2011, and 23 full-size 40-megapixel camera JPEGs. Full method and numbers in benchmarks.md.
| Change | Effect (CUB, 11,788 photos) |
|---|---|
| Batched embedding | Peak memory 41.9 GB → 1.57 GB (27× less) at the same speed |
| Batch size 1 → 32 | 2.6× faster embedding |
src/wildsearch/
cli.py Typer commands; output only, no logic
scanner.py finds image files recursively, with size and mtime
images.py opens a file as an upright RGB image
embedder.py the Embedder protocol
clip.py ClipEmbedder (open_clip); the only module that imports PyTorch
store.py SQLite: photos, vectors per (photo, model), indexed folders
indexer.py sync a folder with the index, embed what's missing
search.py rank stored vectors against a query vector
- JPEG, PNG, WebP and TIFF only; camera RAW and HEIC are not supported yet.
- A corrupt image currently stops
index. --openis macOS-only.