Install & Compatibility
Where this runs
tested against v0.26.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.000s · 31MB
29MB installed
● package 29MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SchemaBuilder
✓ from tantivy import SchemaBuilder
✗ from tantivy.schema import SchemaBuilder
Most core classes are directly under the 'tantivy' top-level module.
This quickstart demonstrates how to define a schema, create an in-memory Tantivy index, add documents to it, and perform a basic search. It also shows how to retrieve the full document content from search hits.
import tantivy
import os
# 1. Declare the schema
schema_builder = tantivy.SchemaBuilder()
schema_builder.add_text_field("title", stored=True, tokenizer_name="default")
schema_builder.add_text_field("body", stored=True, tokenizer_name="default")
schema_builder.add_integer_field("doc_id", stored=True, indexed=True)
schema = schema_builder.build()
# 2. Create an in-memory index (for persistent, specify a path)
# To use a persistent index, use: index = tantivy.Index(schema, path="/tmp/my_index")
index = tantivy.Index(schema)
# 3. Get an index writer and add documents
writer = index.writer(50_000_000) # 50MB memory arena
writer.add_document(tantivy.Document(title=["The Old Man and the Sea"], body=["He was an old man who fished alone in a skiff."], doc_id=[1]))
writer.add_document(tantivy.Document(title=["The Great Gatsby"], body=["In my younger and more vulnerable years my father gave me some advice."], doc_id=[2]))
writer.commit()
# 4. Get a reader and searcher
index.reload()
reader = index.reader()
searcher = reader.searcher()
# 5. Build and execute a query
query_parser = tantivy.QueryParser(schema, default_fields=["title", "body"])
query = query_parser.parse_query("old man")
hits = searcher.search(query, 10)
# 6. Retrieve documents
print("Search results:")
for score, doc_address in hits:
retrieved_doc = searcher.doc(doc_address)
print(f" Score: {score:.2f}, Doc ID: {retrieved_doc['doc_id'][0]}, Title: {retrieved_doc['title'][0]}")
# Example of retrieving a non-existent field (will be empty list)
missing_field = retrieved_doc.get('non_existent_field')
print(f" Non-existent field for last doc: {missing_field}") # Expected: []
Errors
Common errors & fixes
Failed building wheel for tantivy
The Rust toolchain (rustup, rustc, cargo) is not installed, which is required to compile the Tantivy Python bindings during `pip install`.
fixInstall the Rust toolchain using `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` and ensure it's in your PATH before reinstalling `tantivy`.
tantivy.TantivyError: IO error: No such file or directory (os error 2)
The specified directory for opening an existing Tantivy index does not exist or is not a valid Tantivy index directory.
fixEnsure the directory path is correct and points to an existing Tantivy index, or use `Index.create_in_dir()` to create a new index if it doesn't exist.
tantivy.TantivyError: TypeMismatch(U64, Text)
Attempting to add a value of a type (e.g., text) that does not match the field type (e.g., U64) defined in the Tantivy schema for that field.
fixEnsure that the data type of the value being added to a document matches the data type defined for the corresponding field in the schema (e.g., use `doc.add_u64()` for a U64 field).
tantivy.TantivyError: Query parsing error: Invalid query.
The provided query string contains syntax errors, unclosed quotes, unmatched parentheses, or unsupported query language features.
fixCorrect the syntax of the query string according to Tantivy's query language rules, ensuring all operators, terms, and phrases are properly formed and balanced.
Upgrade
Version history
0.26.0latest on PyPI · released Apr 29, 2026
Audit
Dependencies
RustrequiredRequired for building from source if a pre-compiled wheel is not available for your system. Tantivy-py uses PyO3 bindings which rely on Rust.