Skip to content
Get packs

Guide · Open source

How to use LEANN: install, build an index and search locally

Updated · written with AI from the project's own documentation and checked against our catalogue data

LEANN is an open-source Python tool that builds a searchable index of your personal documents, such as files, emails and chat logs, so an AI assistant can pull in relevant passages before it answers. This guide shows you how to install it with uv, what it needs, and where it fits compared with other vector databases. By the end you will know how to set up a local environment and what the project does and does not cover.

LEANNStarTrail-org/LEANN · ★ 13.8k · MIT

Quick start

  1. 1Install uv. Run the uv install script from the official uv docs if you do not already have uv.
  2. 2Clone the repository. Clone StarTrail-org/LEANN into a folder called leann and change into it.
  3. 3Create a virtual environment. Run uv venv, then activate it with source .venv/bin/activate.
  4. 4Install LEANN from PyPI. Run uv pip install leann inside the activated environment.
  5. 5Build an index. Use the leann build command from the examples in the repo, following the README and docs for your data source.
  6. 6Search and connect. Query your index locally, or use the MCP package if you want a coding agent to call it.

What LEANN does and why it is different

LEANN is a vector database built for retrieval-augmented generation (RAG) on a personal device. Instead of storing every embedding, it recomputes embeddings on demand, which the project says cuts storage by about 97% without accuracy loss.

Your data stays on your laptop. The README states there is no OpenAI and no cloud involved in the core setup.

  • Privacy: data never leaves your laptop, according to the README.
  • Lightweight: graph-based recomputation reduces embedding storage.
  • Portable: you can move a knowledge base between devices.

Check the prerequisites before you install

LEANN requires Python 3.10 or newer. The README badges list Python 3.10 through 3.14. You also need the uv package manager, which handles the virtual environment and package installs.

The README lists Ubuntu, Arch, WSL, macOS (ARM64 and Intel) and Windows as platforms.

  • Python 3.10 or newer
  • uv package manager

Install uv, clone the repo and install LEANN from PyPI

If you do not have uv, install it with the command below. The README links to the uv installation guide for other methods.

Clone the repository to access the examples, then create a virtual environment and install LEANN from PyPI. On Linux, the README notes a CPU-only option using the cpu extra, written as leann[cpu].

curl -LsSf https://astral.sh/uv/install.sh | sh git clone https://github.com/StarTrail-org/LEANN.git leann cd leann uv venv source .venv/bin/activate uv pip install leann

Fix the Linux multiply-linked file error

On Linux, a later leann build may fail with the message Security Violation [pathsec.open]: refusing multiply-linked file. The README says this comes from uv's default hardlink installs clashing with nltk's file loader bundled with llama-index.

The README's fix is to reinstall with copy link mode. Details are in the project FAQ at docs/faq.md.

UV_LINK_MODE=copy uv pip install --reinstall leann

Build from source for development

The README recommends building from source for development. This path clones the repo, initialises submodules and installs the DiskANN extra with uv sync. Platform steps differ for macOS, Ubuntu/Debian and Arch Linux, and DiskANN needs system libraries such as libomp, boost and protobuf.

On macOS the README says DiskANN requires macOS 13.3 or later. On Ubuntu 20.04 you may need to build a newer Abseil and pin Protobuf, so check the linked issue before you start.

  • Clone the repo and run git submodule update --init --recursive
  • macOS: install the listed Homebrew packages, then run uv sync --extra diskann
  • Ubuntu/Debian: install the listed apt packages, then run uv sync --extra diskann
git clone https://github.com/StarTrail-org/LEANN.git leann cd leann git submodule update --init --recursive uv sync --extra diskann

Use LEANN with a coding agent through MCP

The README says Claude Code only supports grep-style keyword search, and that LEANN is a drop-in semantic search MCP service that works with Claude Code. Its MCP package has its own README with setup steps at packages/leann-mcp/README.md.

The project also ran a benchmark against BM25 on 30 SWE-Bench Pro tasks from ContextBench. The README reports 2.1 times the initial relevant-code recall, but notes that better context access does not guarantee issue resolution.

What people use it for

  • Building a private RAG prototype on a personal machine.
  • Semantically searching your own files or notes without uploading them.
  • Giving a coding agent semantic code search through an MCP service.
  • Indexing a large document collection when disk space is limited.

Frequently asked questions

Is LEANN free and open source?

Yes. The repository is licensed under MIT, as shown in the README badge and project metadata. You can install it from PyPI with uv pip install leann.

What do I need to install LEANN?

You need Python 3.10 or newer and the uv package manager. The README lists Ubuntu, Arch, WSL, macOS and Windows as supported platforms.

How do I install LEANN?

Install uv, clone the repository, create a virtual environment with uv venv, activate it, and run uv pip install leann. On Linux you can use the cpu extra for a CPU-only install.

Why does leann build fail with a security violation on Linux?

The README says uv's default hardlink install can trigger a refusing multiply-linked file error with nltk's loader in llama-index. Reinstall with UV_LINK_MODE=copy, and see the project FAQ at docs/faq.md for details.

Does LEANN use a GPU?

Not yet. The README says GPU acceleration is only being considered, based on votes in the community survey.

How does LEANN compare with Chroma, LlamaIndex, FAISS or Qdrant?

The source does not include a direct comparison with these projects. LEANN's README focuses on storage savings and a personal, single-device setup, so check each project's documentation against your needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

LEANN suits developers and technical users who want a private, local semantic search index over personal files, notes or code, and who are comfortable with a command-line Python setup. It is a poor fit if you need a hosted multi-user database, a polished app with no terminal, or GPU acceleration today.

Install options & downloads