Local Lens

Web application for finding images in your local directories using natural language queries or reverse image search. Powered by vision embedding models (e.g., CLIP/SigLIP 2).

Table of Contents

• Features
• Requirements
• Install
• Usage
• Documentation
• Updating
• License & Credits

Features

• Indexing: Index and update local image directories recursively using ChromaDB
• Search: Find relevant images or videos with text, image, or combined text + image queries
• Reverse Search: Upload an image to retrieve visually similar matches
• Duplicates: Retrieve duplicate or highly similar image pairs from indexed directories
• Results: Display matches in a confidence-ordered gallery
• Interface: Web UI (Gradio)

Requirements

• Python 3.10+
• PyTorch (CPU, CUDA, ROCm, XPU, MPS)

Install

Portable Package (Recommended)

Download the standalone zip from the releases page: Portable Build

Requirements:

• Windows: Bundled Python/Git included; no additional requirements
• Linux/macOS: Python 3.10+ and Git must be installed on your system

Setup:

1. Extract the zip file
2. Run the setup script for your platform:
   • Windows: Double-click setup.bat
   • Linux/macOS: Run ./setup.sh in terminal
3. The setup wizard will:
   • Detect your GPU and install the appropriate PyTorch version
   • Install all required dependencies
   • Create a launcher script (start-webui.bat or start-webui.sh)

Tip

In the event that you need to transfer to a fresh portable package:

• You can safely move the img_db directory to the new portable package
• You might be able to move the runtime directory over, assuming the same setup configuration is wanted

Manual install

1. Clone and enter the repo

git clone https://github.com/meangrinch/LocalLens.git
cd LocalLens

2. Create and activate a virtual environment (recommended)

python -m venv venv
# Windows PowerShell/CMD
.\venv\Scripts\activate
# Linux/macOS
source venv/bin/activate

3. Install PyTorch (see: PyTorch Install)

# Example (CUDA 13.0)
pip install torch==2.12.0+cu130 torchvision==0.27.0+cu130 --extra-index-url https://download.pytorch.org/whl/cu130
# Example (ROCm 7.1)
pip install torch==2.12.0+rocm7.1 torchvision==0.27.0+rocm7.1 --extra-index-url https://download.pytorch.org/whl/rocm7.1
# Example (XPU)
pip install torch==2.12.0+xpu torchvision==0.27.0+xpu --extra-index-url https://download.pytorch.org/whl/xpu
# Example (MPS/CPU)
pip install torch==2.12.0 torchvision==0.27.0

4. Install dependencies

pip install -r requirements.txt

Usage

Web UI (Gradio)

1. Select a model (automatically downloads to hugging face cache ~/.cache/huggingface/hub)
2. Add image directories to your Chroma database (via the "Database Management" dropdown in the UI, or via CLI)
3. Enter your search query (e.g., "an orange and black butterfly") and/or upload an image (for reverse image search/combined text + image search)
4. The application will display the results in order of confidence
5. Update/sync indexed directories if necessary

Find duplicates

Click "Find Duplicates" in the UI with a specified indexed image directory to return similar matching images pairs.

Local file access

The Gradio gallery is launched with broad local file access by default so it can display image paths from any indexed folder. To restrict this, set LOCALLENS_ALLOWED_PATHS to an OS path-list before launching the app.

Documentation

• Hardware Requirements

Updating

Portable Package

• Windows: Run update.bat from the portable package root
• Linux/macOS: Run ./update.sh from the portable package root

Manual Install

From the repo root:

git pull
pip install -r requirements.txt  # Or activate venv first if present

License & credits

• License: Apache-2.0 (see LICENSE)
• Author: grinnch
• Inspired by Where's My Pic? by @Om-Alve