{"id":13495332,"url":"https://github.com/yurijmikhalevich/rclip","last_synced_at":"2026-05-15T09:18:26.964Z","repository":{"id":40647492,"uuid":"373897031","full_name":"yurijmikhalevich/rclip","owner":"yurijmikhalevich","description":"AI-Powered Command-Line Photo Search Tool","archived":false,"fork":false,"pushed_at":"2025-03-15T20:23:57.000Z","size":55322,"stargazers_count":804,"open_issues_count":26,"forks_count":63,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-12T14:37:01.704Z","etag":null,"topics":["artificial-intelligence","computer-vision","hacktoberfest","image-search","photography","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yurijmikhalevich.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-06-04T16:13:21.000Z","updated_at":"2025-04-09T14:00:17.000Z","dependencies_parsed_at":"2023-11-25T22:24:27.910Z","dependency_job_id":"2fe743b7-5770-46e5-b6a5-d9489220acb3","html_url":"https://github.com/yurijmikhalevich/rclip","commit_stats":{"total_commits":221,"total_committers":4,"mean_commits":55.25,"dds":0.02714932126696834,"last_synced_commit":"1be39dc13ff694161be18a7f2cea11bf9b034e63"},"previous_names":[],"tags_count":302,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurijmikhalevich%2Frclip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurijmikhalevich%2Frclip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurijmikhalevich%2Frclip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurijmikhalevich%2Frclip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yurijmikhalevich","download_url":"https://codeload.github.com/yurijmikhalevich/rclip/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254129489,"owners_count":22019628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","computer-vision","hacktoberfest","image-search","photography","python"],"created_at":"2024-07-31T19:01:33.650Z","updated_at":"2026-05-15T09:18:26.952Z","avatar_url":"https://github.com/yurijmikhalevich.png","language":"Python","funding_links":[],"categories":["Applications","Python","Images","\u003ca name=\"graphics\"\u003e\u003c/a\u003eGraphics"],"sub_categories":["Graphics","Emoji"],"readme":"# rclip - AI-Powered Semantic Photo Search for the Command Line\n\u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n[![All Contributors](https://img.shields.io/badge/all_contributors-6-orange.svg?style=flat-square)](#contributors-)\n\u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n\n[[Blog]](https://mikhalevi.ch/rclip-an-ai-powered-command-line-photo-search-tool/) [[Demo on YouTube]](https://www.youtube.com/watch?v=tAJHXOkHidw) [[Paper]](https://www.thinkmind.org/index.php?view=article\u0026articleid=content_2023_1_20_60011)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg alt=\"rclip logo\" src=\"https://raw.githubusercontent.com/yurijmikhalevich/rclip/main/resources/logo-transparent.png\" width=\"600px\" /\u003e\n\u003c/div\u003e\n\n**rclip** is a command-line semantic photo search tool powered by [OpenCLIP's top-performing ViT-B/32 model](https://github.com/mlfoundations/open_clip/blob/55794d65a14dfc547a9ed3514145dd68ccc939e9/README.md). 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.\n\n## Installation\n\n### Linux\n\n```bash\nsudo snap install rclip\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eAlternative options (AppImage and \u003ccode\u003epip\u003c/code\u003e)\u003c/summary\u003e\n\n  If your Linux distribution doesn't support [snap](https://snapcraft.io/rclip), you can use one of the alternative installation options:\n\n  #### AppImage (self-contained x86_64 executable)\n\n  On Linux x86_64, you can install **rclip** as a self-contained executable.\n\n  1. Download the AppImage from the [latest release](https://github.com/yurijmikhalevich/rclip/releases/latest).\n\n  2. Execute the following commands:\n\n  ```bash\n  chmod +x \u003cdownloaded AppImage filename\u003e\n  sudo mv \u003cdownloaded AppImage filename\u003e /usr/local/bin/rclip\n  ```\n\n  #### Using \u003ccode\u003epip\u003c/code\u003e\n\n  ```bash\n  pip install --extra-index-url https://download.pytorch.org/whl/cpu rclip\n  ```\n\u003c/details\u003e\n\n### macOS\n\n```bash\nbrew install yurijmikhalevich/tap/rclip\n```\n\n**Note:** We only support Apple Silicon (arm64) on macOS.\n\n\u003cdetails\u003e\n  \u003csummary\u003eAlternative option (\u003ccode\u003epip\u003c/code\u003e)\u003c/summary\u003e\n\n  ```bash\n  pip install rclip\n  ```\n\u003c/details\u003e\n\n### Windows\n\n1. Download the \"*.msi\" from the [latest release](https://github.com/yurijmikhalevich/rclip/releases/latest).\n2. Install **rclip** by running the installer.\n\n\u003cdetails\u003e\n  \u003csummary\u003eAlternative option (\u003ccode\u003epip\u003c/code\u003e)\u003c/summary\u003e\n\n  ```bash\n  pip install rclip\n  ```\n\u003c/details\u003e\n\n## Usage\n\nSearch the current directory with a natural-language query:\n\n```bash\ncd photos \u0026\u0026 rclip \"search query\"\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eExample output\u003c/summary\u003e\n\n  ```text\n  score  filepath\n  0.297  \"/photos/sunrise-beach.jpg\"\n  0.286  \"/photos/dawn-walk.png\"\n  0.274  \"/photos/morning-hike.heic\"\n  ```\n\u003c/details\u003e\n\n\u003cimg alt=\"rclip usage demo\" src=\"https://raw.githubusercontent.com/yurijmikhalevich/rclip/main/resources/rclip-usage.gif\" width=\"640px\" /\u003e\n\nThe 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.\n\nFor a detailed demonstration, watch the video: https://www.youtube.com/watch?v=tAJHXOkHidw.\n\n### Similar image search (image-to-image search)\n\nYou 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:\n\n```bash\ncd photos \u0026\u0026 rclip ./cat.jpg\n\n# or use URL\ncd photos \u0026\u0026 rclip https://raw.githubusercontent.com/yurijmikhalevich/rclip/main/tests/e2e/images/cat.jpg\n```\n\nCheck this video out for the image-to-image search demo: https://www.youtube.com/watch?v=1YQZKeCBxWM.\n\n### Combining multiple queries\n\nYou can combine and subtract image and text queries; here are a few examples:\n\n```bash\ncd photos \u0026\u0026 rclip horse + stripes\ncd photos \u0026\u0026 rclip apple - fruit\ncd photos \u0026\u0026 rclip \"./new york city.jpg\" + night\ncd photos \u0026\u0026 rclip \"2:golden retriever\" + \"./swimming pool.jpg\"\ncd photos \u0026\u0026 rclip \"./racing car.jpg\" - \"2:sports car\" + \"2:snow\"\n```\n\nIf 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.\n\n### How do I preview the results?\n\nIf you are using either [iTerm2](https://iterm2.com/), [Konsole](https://konsole.kde.org/) (version 22.04 and higher), [wezterm](https://wezfurlong.org/wezterm/), [Mintty](https://mintty.github.io/), or [mlterm](https://mlterm.sourceforge.net/), all you need to do is pass the `--preview` (or `-p`) flag to **rclip**:\n\n```bash\nrclip -p kitty\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eUsing a different terminal or viewer\u003c/summary\u003e\n\n  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:\n\n  ```bash\n  rclip -f -t 5 kitty | xargs -d '\\n' -n 1 xdg-open\n  ```\n\n  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.\n  \n  I prefer to use **feh**'s thumbnail mode to preview multiple results:\n\n  ```bash\n  rclip -f -t 5 kitty | feh -f - -t\n  ```\n\u003c/details\u003e\n\n### Can I use **rclip** to copy images matching a certain query?\n\nYes. 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:\n\n```sh\nrclip -f -t 3 \"search query\" | xargs -I {} cp {} /path/to/destination\n```\n\n### How does **rclip** update the index?\n\nWhen you run **rclip** in a directory that has already been processed, it indexes\nonly the new images added since the last run and removes deleted images from its\nindex. This makes consecutive runs much faster.\n\nIf you know no images have been added or deleted since the last run, you can use\nthe `--no-indexing` (or `-n`) flag to skip indexing entirely and speed up the\nsearch even more.\n\n```bash\nrclip -n cat\n```\n\n## Get help\n\nhttps://github.com/yurijmikhalevich/rclip/discussions/new/choose\n\n## Contributing\n\nThis repository follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard.\n\n### Running locally from the source code\n\nTo run **rclip** locally from source, you must have [Python](https://www.python.org/downloads/) and [uv](https://docs.astral.sh/uv/) installed.\n\nThen run:\n```bash\n# clone the source code repository\ngit clone git@github.com:yurijmikhalevich/rclip.git\n\n# install dependencies and rclip\ncd rclip\nuv sync\n```\n\nThen use `uv run rclip`, as described in the [Usage](#usage) section above.\n\n## Contributors ✨\n\nThanks go to these wonderful people and organizations ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/ramayer\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/72320?v=4?s=100\" width=\"100px;\" alt=\"ramayer\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eramayer\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/yurijmikhalevich/rclip/commits?author=ramayer\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://www.caphyon.com\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/15829334?v=4?s=100\" width=\"100px;\" alt=\"Caphyon\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eCaphyon\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#infra-Caphyon\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e🚇\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://abidkhan484.github.io\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/15053047?v=4?s=100\" width=\"100px;\" alt=\"AbId KhAn\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAbId KhAn\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/yurijmikhalevich/rclip/commits?author=abidkhan484\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://cl4r1ty.dev\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/136800640?v=4?s=100\" width=\"100px;\" alt=\"Ben\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eBen\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/yurijmikhalevich/rclip/commits?author=Cl4r1ty-1\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://techtracer.pages.dev\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/48885301?v=4?s=100\" width=\"100px;\" alt=\"Tanmay Chaudhari\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eTanmay Chaudhari\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/yurijmikhalevich/rclip/commits?author=tanmayc07\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://leoauri.com\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/10868855?v=4?s=100\" width=\"100px;\" alt=\"Leo Auri\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eLeo Auri\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/yurijmikhalevich/rclip/commits?author=leoauri\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThanks to [Caphyon](https://github.com/Caphyon) and the Advanced Installer team for generously supplying the **rclip** project with the Professional Advanced Installer license for creating the Windows installer.\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome!\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyurijmikhalevich%2Frclip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyurijmikhalevich%2Frclip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyurijmikhalevich%2Frclip/lists"}