rclip 3.0.8

AI-Powered Command-Line Photo Search Tool

rclip - AI-Powered Semantic Photo Search for the Command Line

[Blog] [Demo on YouTube] [Paper]

rclip is a command-line semantic photo search tool powered by OpenCLIP's top-performing ViT-B/32 model. Search a local photo library with natural-language queries, similar image search, or mixed text and image queries directly from the terminal. It builds on the CLIP architecture introduced by OpenAI.

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 about a day to process 73,000 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.

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

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