PixSearch is a local AI photo search app that finds images by description or visual similarity. I built it for the moments when you remember a red umbrella on a rainy street but have no idea what the file is called. The app indexes a folder on your computer, then lets you search it in your browser.
How local AI photo search works
CLIP turns photos and text into numerical representations called embeddings. PixSearch stores the photo embeddings in PostgreSQL with pgvector. When you describe a photo, the app embeds your query and ranks the indexed photos by cosine similarity. “Find similar” reuses the selected photo’s stored embedding and excludes that photo from the results.
FastAPI serves search results and thumbnails to a React and TypeScript interface. The indexer checks file hashes on repeat runs, so it only needs to embed new or changed files.
How to set up PixSearch
You’ll need Git, Python 3.11 or newer, Docker, Node.js 20 or newer, and Make for the commands below. Start Docker before running the setup.
1. Clone the repo and install the backend. Run these commands from a shell that has Make available.
git clone https://github.com/shasha1589/pixsearch.git
cd pixsearch
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev,serve]"For Windows PowerShell, use .\.venv\Scripts\Activate.ps1 in place of the source command.
2. Index the sample photos and start the API. From the repository root, run the commands below. The first command starts PostgreSQL, initializes the schema, and indexes the sample folder. The first run downloads the CLIP model weights. Leave the API running on port 8000.
make dev
make serve3. Start the web interface. In a second terminal, start from the repository root and run the following commands. Open the local URL Vite prints, usually http://localhost:5173.
cd frontend
npm install
npm run devHow to search and find similar photos
1. Search by description. Try “a sunset” or “a forest” with the synthetic sample images. For your own collection, describe a subject, setting, or color you remember.
2. Refine your results. Move the similarity slider up for closer matches or down to see more results. Use the camera filter when your photos have camera metadata.
3. Find similar images. Open a result and choose “Find similar” to look for other photos that resemble it.
4. Index your own library. With PostgreSQL running, open a terminal in the repository root, activate the Python environment, and run this command with your photo folder’s path.
python -m backend.index_cli "/path/to/your/photos"Do photos leave your computer?
PixSearch processes photos on your computer and stores embeddings in your local PostgreSQL database. After the one-time model download, indexing and search can run offline. The default model configuration runs on a CPU.
A model configuration detail that mattered
Running the real model on the sample images exposed a mismatch between the original CLIP model configuration and the OpenAI checkpoint. Switching to the matching QuickGELU variant fixed the mismatch. It was a useful reminder to test the model and its weights together.