Registry / database / tantivy

tantivy

JSON →
library0.26.0pypypi✓ verified 24d ago

Tantivy-py provides official Python bindings for Tantivy, a high-performance full-text search engine library written in Rust and inspired by Apache Lucene. It offers fast indexing and search capabilities. The current version is 0.25.1, and the project maintains an active development cycle with relatively frequent releases of minor versions, often a few months apart.

pip install tantivy
INSTALL
IMPORT
SIG · TANTIVY
T
tantivy
databasepythonv0.26.0
Install
1.8s avg
Import
Disk
29MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
build_error
glibc
py 3.103.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.

tantivy
import tantivy
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: []
Debug
Known issues
gotchaTo install `tantivy` from source (if no pre-compiled wheel is available for your system), you must have Rust installed and configured. This is a common requirement for Python libraries with Rust bindings.
fix
Install Rust via `rustup` before attempting `pip install tantivy`.
affects: All versions
breakingVersion 0.25.0 introduced a breaking API change by removing index sorting. Users relying on this feature will need to adjust their indexing and search strategies.
fix
Review the Tantivy Rust documentation (or tantivy-py changelog) for alternatives or re-architect solutions that previously relied on index sorting.
affects: >=0.25.0
gotchaTantivy treats document data as immutable. To 'edit' a document, you must delete the existing document (by its `DocAddress` or a specific term query) and then reindex the updated version.
fix
Implement a delete-and-reindex strategy for document updates.
affects: All versions
gotchaOnly one `IndexWriter` can be active at a time for a given index. While the `IndexWriter` itself is multithreaded, concurrent attempts to create multiple writers will fail.
fix
Manage access to the `IndexWriter` to ensure singularity, typically by having a single process or thread manage all write operations to an index, or using a locking mechanism in multi-process/thread scenarios.
affects: All versions
gotchaSearch operations return a list of `(score, DocAddress)` tuples. To retrieve the actual document content, you must use the `DocAddress` with a `Searcher`'s `doc()` method, rather than receiving the document directly in search results.
fix
Always use `searcher.doc(doc_address)` to fetch the stored fields of a document after a search.
affects: All versions
gotchaFor incremental indexing and efficient document deletion, the field used to identify documents for deletion (e.g., a unique ID) must be an integer field, set to `indexed=True` and `fast=True` in the schema.
fix
Ensure your schema defines the unique ID field with `tantivy.SchemaBuilder.add_integer_field("your_id_field", stored=True, indexed=True, fast=True)`.
affects: All versions
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`.
fix
Install 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.
fix
Ensure 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.
fix
Ensure 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.
fix
Correct 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.
Agent activity
22 hits · last 30 days
node
18
Meta
1
OpenAI (training)
1
Resources
tantivy — pip install tantivy · libregistry