rclip 3.2.4

Semantic photo search for the command line

rclip – semantic photo search for the command line

[Blog] [Demo on YouTube] [Paper]

rclip is a semantic photo search tool for the command line, powered by OpenCLIP's top-performing ViT-B/32 AI model. Search a local photo library with natural-language queries, similar image search, or mixed text and image queries – entirely on your machine, with no cloud and no uploads. It builds on the CLIP architecture introduced by OpenAI.

Features

• Natural-language search – find photos by describing them, e.g. rclip "two parrots on a branch".
• Reverse / image-to-image search – search by an example image from a local path or a URL.
• Combined & arithmetic queries – mix and weight text and image queries, e.g. rclip "2:golden retriever" + "./pool.jpg" - fruit.
• Local & private – works fully offline; your photos never leave your computer.
• Wide format support – jpg, png, webp, heic, tiff, gif, and more, plus experimental RAW (arw, cr2, dng).
• Fast incremental indexing – only new and changed images are reprocessed on subsequent runs.
• Terminal previews – view images inline in iTerm2, Konsole, wezterm, Mintty, and mlterm.
• Cross-platform – Linux, macOS (Apple Silicon), and Windows.

Installation

Linux

sudo snap install rclip

Alternative options (AppImage and pip)

If your Linux distribution doesn't support snap, you can use one of the alternative installation options:

AppImage (self-contained x86_64 executable)

On Linux x86_64, you can install rclip as a self-contained executable.

1. Download the AppImage from the latest release.

2. Execute the following commands:

chmod +x <downloaded AppImage filename>
sudo mv <downloaded AppImage filename> /usr/local/bin/rclip

Using pip

pip install --extra-index-url https://download.pytorch.org/whl/cpu rclip

macOS

brew install yurijmikhalevich/tap/rclip

Note: We only support Apple Silicon (arm64) on macOS.

Alternative option (pip)

pip install rclip

Windows

1. Download the "*.msi" from the latest release.
2. Install rclip by running the installer.

Alternative option (pip)

pip install rclip

Usage

Search the current directory with a natural-language query:

cd photos && rclip "search query"

Example output

score  filepath
0.297  "/photos/sunrise-beach.jpg"
0.286  "/photos/dawn-walk.png"
0.274  "/photos/morning-hike.heic"

The first time you run rclip in a directory, it extracts features from your images to build the search index. How long this takes depends on your CPU and the number of images you search. On my hardware, it took 15 hours to process 84,725 photos on a NAS with an old Intel Celeron J3455, 7 minutes to index 50,000 images on a MacBook with an M1 Max, and 3 hours to process 1.28 million images on the same MacBook.

For a detailed demonstration, watch the video: https://www.youtube.com/watch?v=tAJHXOkHidw.

Similar image search (image-to-image search)

You can also use an image as the query by passing a file path or image URL. rclip will return the images most similar to that query image. If you use a relative path to a local image, you must prefix it with ./. For example:

cd photos && rclip ./cat.jpg

# or use URL
cd photos && rclip https://raw.githubusercontent.com/yurijmikhalevich/rclip/main/tests/e2e/images/cat.jpg

Check this video out for the image-to-image search demo: https://www.youtube.com/watch?v=1YQZKeCBxWM.

Combining multiple queries

You can combine and subtract image and text queries; here are a few examples:

cd photos && rclip horse + stripes
cd photos && rclip apple - fruit
cd photos && rclip "./new york city.jpg" + night
cd photos && rclip "2:golden retriever" + "./swimming pool.jpg"
cd photos && rclip "./racing car.jpg" - "2:sports car" + "2:snow"

If you want to see how these queries perform when executed on the 1.28 million images ImageNet-1k dataset, check out the demo on YouTube: https://www.youtube.com/watch?v=MsTgYdOpgcQ.

Which formats does rclip support?

rclip always indexes the following image formats: jpg, jpeg, png, webp, heic, tiff, tif, bmp, gif, jp2, pnm, pbm, pgm, and ppm.

RAW formats (arw, cr2, and dng) are supported when you pass the --experimental-raw-support flag:

rclip --experimental-raw-support cat

When this flag is enabled, a RAW file is skipped if a processed image (e.g., a JPEG) with the same name sits alongside it, so previews and exported variants are indexed instead of the RAW original.

How do I preview the results?

If you are using either iTerm2, Konsole (version 22.04 and higher), wezterm, Mintty, or mlterm, all you need to do is pass the --preview (or -p) flag to rclip:

rclip -p kitty

Using a different terminal or viewer

If you use another terminal or want to open the results in a viewer of your choice, you can pipe rclip's output into it. For example, on Linux, the command below will open the top 5 results for "kitty" in your default image viewer:

rclip -f -t 5 kitty | xargs -d '\n' -n 1 xdg-open

The -f or --filepath-only flag makes rclip print only file paths, without scores or the header, which makes it ideal for use with a custom viewer as in the example.

I prefer to use feh's thumbnail mode to preview multiple results:

rclip -f -t 5 kitty | feh -f - -t

Can I use rclip to copy images matching a certain query?

Yes. You can pipe rclip's output to another tool to copy matching images. For example, to copy the top 3 images matching "search query" to /path/to/destination on macOS, Linux, or WSL:

rclip -f -t 3 "search query" | xargs -I {} cp {} /path/to/destination

How does rclip update the index?

When you run rclip in a directory that has already been processed, it indexes only the new images added since the last run and removes deleted images from its index. This makes consecutive runs much faster.

If you know no images have been added or deleted since the last run, you can use the --no-indexing (or -n) flag to skip indexing entirely and speed up the search even more.

rclip -n cat

Command-line options

Run rclip --help (or rclip -h) to see this list in your terminal. The positional query and all options are summarized below:

Option	Description
query	A text query or a path/URL to an image file. A relative path must be prefixed with ./ (e.g. ./cat.jpg). Any query can be prefixed with a multiplier, e.g. 2:cat or 0.5:./cat.jpg.
--add, -a, + QUERY	A text query or a path/URL to an image file to add to the "original" query. Can be used multiple times.
--subtract, --sub, -s, - QUERY	A text query or a path/URL to an image file to subtract from the "original" query. Can be used multiple times.
--top, -t N	Number of top results to display. Default: 10.
--preview, -p	Preview results in the terminal (supported in iTerm2, Konsole 22.04+, wezterm, Mintty, mlterm). Mutually exclusive with --filepath-only.
--filepath-only, -f	Output only filepaths, without scores or the header. Mutually exclusive with --preview.
--preview-height, -H PX	Preview height in pixels. Default: 400.
--no-indexing, --skip-index, --skip-indexing, -n	Skip updating the index. Use only when no images were added, changed, or removed since the last run.
--indexing-batch-size, -b N	The size of the image batch used when updating the search index. Larger values may slightly improve indexing speed on some hardware but increase RAM usage. Default: 8.
--exclude-dir DIR	Directory to exclude from search. Can be used multiple times. Specifying this overrides the default of @eaDir, node_modules, and .git.
--experimental-raw-support	Enable support for RAW images (arw, cr2, and dng are supported).
--version, -v	Print the rclip version and exit.
--help, -h	Show the help message and exit.

Get help

https://github.com/yurijmikhalevich/rclip/discussions/new/choose

Contributing

This repository follows the Conventional Commits standard.

Running locally from the source code

To run rclip locally from source, you must have Python and uv installed.

Then run:

# clone the source code repository
git clone [e-mail]:yurijmikhalevich/rclip.git

# install dependencies and rclip
cd rclip
uv sync

Then use uv run rclip, as described in the Usage section above.

Contributors ✨

Thanks go to these wonderful people and organizations (emoji key):

ramayer 💻

Caphyon 🚇

AbId KhAn 💻

Ben 💻

Tanmay Chaudhari 💻

Leo Auri 💻

Thanks to Caphyon and the Advanced Installer team for generously supplying the rclip project with the Professional Advanced Installer license for creating the Windows installer.

This project follows the all-contributors specification. Contributions of any kind are welcome!

License

MIT