Skip to content
Get packs

Guide · Open source

How to use Tantivy: install, build and search with Rust

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

Tantivy is a full-text search library written in Rust and inspired by Apache Lucene. It is a building block for developers, not a ready-made search server. This guide explains what it is, how to get the source and run its tests, which features matter, and how to decide whether it fits your project.

Tantivyquickwit-oss/tantivy · ★ 16.4k · MIT

Quick start

  1. 1Check your Rust toolchain. Confirm you have the Rust stable toolchain and cargo installed. Tantivy compiles on stable Rust.
  2. 2Clone the repository. Run git clone https://github.com/quickwit-oss/tantivy.git to get the source code.
  3. 3Enter the directory. Change into the cloned folder with cd tantivy.
  4. 4Run the tests. Run cargo test to build the project and check that the test suite passes.
  5. 5Read the basic search example. Open the basic search example on the Tantivy site to see how to create an index and run a query.
  6. 6Add Tantivy to your project. Use the reference documentation on docs.rs to find the version and API you need for your own crate.

What Tantivy is and when to use it

Tantivy is a crate, meaning a Rust library you include in your own program. It is not an off-the-shelf search engine with a REST API. Its design is close to Apache Lucene, and the README describes it as a crate used to build a search engine rather than a server.

It suits Rust developers who need search inside an application, teams building a custom search engine, and command-line tools that need fast startup. The README cites startup time under 10ms.

  • Good fit: search embedded in a Rust application
  • Good fit: a custom search engine with Lucene-style design
  • Poor fit: a search server you can query over HTTP out of the box
  • Poor fit: distributed search across several machines

Install prerequisites and get the source

Tantivy works on stable Rust and supports Linux, macOS and Windows. The install method described in the source is cloning the repository and building it, so you need the Rust stable toolchain with cargo installed.

Clone the repository, then move into the directory:

  • Prerequisite: Rust stable toolchain (with cargo)
  • Supported platforms: Linux, macOS and Windows
git clone https://github.com/quickwit-oss/tantivy.git cd tantivy

Build and run the tests

The README says Tantivy compiles on stable Rust, and you can check out the code and run its tests with cargo. Running the test suite is the quickest way to confirm your toolchain works with the project.

To use Tantivy in your own code, the README points to the basic search example and the reference documentation for the last released version.

  • Basic search example: tantivy-search.github.io/examples/basic_search.html
  • Reference documentation: docs.rs/tantivy
cargo test

Key features to know about

Tantivy supports full-text search, BM25 scoring (the same as Lucene), phrase queries, range queries, faceted search and incremental indexing. Queries can use a natural query language such as (michael AND jackson) OR "king of pop".

Text analysis is configurable. Stemming is available for 17 Latin languages, and third-party crates add support for Chinese, Japanese and Korean. Indexing is multithreaded, and the library includes an aggregation collector for histogram, range, average and stats metrics.

  • BM25 scoring and phrase queries
  • Natural query language, for example (michael AND jackson) OR "king of pop"
  • Incremental indexing
  • Facet fields and range queries
  • Stemming for 17 Latin languages
  • Third-party tokenizers for Chinese, Japanese and Korean

Understand indexing and visibility

Tantivy data is immutable. To edit a document, you delete it and reindex it. Documents become searchable after a commit is called on an IndexWriter. Existing IndexReaders must be reloaded to see the changes, and only newly acquired Searchers reflect them.

Distributed search is out of scope for Tantivy. The README points to Quickwit for that need.

  • Edit a document by deleting it and reindexing it
  • Call commit on an IndexWriter to make changes searchable
  • Reload existing IndexReaders, then acquire a new Searcher

Choose the right tool

If you want a ready-made search server, the README suggests tantivy-cli or Quickwit. Tantivy-cli is a command-line interface that can index documents and search them from the CLI or a small server with a REST API. Bindings such as tantivy-py exist for Python, but the README says other bindings may be less maintained.

Comparable projects named in the source include Apache Lucene, Quickwit, Meilisearch and lnx, which is built on Tantivy.

  • Need a server with a REST API: try tantivy-cli or Quickwit
  • Need distributed search: Quickwit
  • Not using Rust: check the bindings, noting they may be less maintained

What people use it for

  • Adding full-text search to a Rust desktop or command-line application
  • Building a custom search engine with Lucene-style design
  • Indexing email archives, as in the Bichon project listed in the source
  • Adding search to a message database, as seshat does for Matrix messages
  • Building a typo-tolerant search engine with a REST API, as lnx does

Frequently asked questions

Is Tantivy free to use?

Tantivy is released under the MIT licence, according to the source. You can read the licence on the project page before using it in your own code.

Is Tantivy a search server?

No. The README says Tantivy is a crate for building a search engine, not an off-the-shelf server. If you need an HTTP API, the README suggests tantivy-cli or Quickwit.

How do I install Tantivy?

The source describes cloning the repository with git clone, entering the directory, and running cargo test. You need the Rust stable toolchain with cargo. Using it in your own project is done through the crate documentation.

Does Tantivy support incremental indexing?

Yes. The FAQ in the source confirms incremental indexing. Documents become searchable after commit is called on an IndexWriter.

Can I use Tantivy from Python or Ruby?

The source lists tantivy-py for Python and tantiny for Ruby. It also notes that other bindings exist but may be less maintained.

How does Tantivy compare with Apache Lucene?

Tantivy is inspired by Lucene's design and uses BM25 scoring, which the README says is the same as Lucene. The FAQ cites a benchmark claiming Tantivy is about 2x faster than Lucene, but the README notes that results vary with queries and load.

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

Tantivy is a good choice for Rust developers who want full-text search inside an application or a custom search engine. If you want a ready-made search server with a REST API or distributed search, pick tantivy-cli, Quickwit or another server-based tool instead.

Install options & downloads