Install & Compatibility
Where this runs
tested against v0.8.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.940 runs
installs and imports cleanly · install 0.0s · import 0.434s · 35.7MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 2.5s · import 0.392s · 37MB
36MB installed
● package 36MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
lunr
✓ from lunr import lunr
✗ import lunr
The primary index creation function is named `lunr` and needs to be explicitly imported from the `lunr` package.
This quickstart demonstrates how to create a Lunr index from a list of dictionaries. It defines a unique reference field (`id`), fields to be searched (`title`, `body`), and the documents themselves. It then performs a basic search and a more precise search using term presence modifiers (`+` for required, `-` for prohibited).
from lunr import lunr
documents = [
{
"id": "1",
"title": "Alice's Adventures in Wonderland",
"body": "Alice was beginning to get very tired of sitting by her sister on the bank, and of having nothing to do: once or twice she had peeped into the book her sister was reading, but it had no pictures or conversations in it, 'and what is the use of a book,' thought Alice 'without pictures or conversation?'"
},
{
"id": "2",
"title": "Through the Looking-Glass",
"body": "One thing was certain, that the white kitten had had nothing to do with it: it was the black kitten's fault entirely."
},
{
"id": "3",
"title": "The Hunting of the Snark",
"body": "'Just the place for a Snark!' the Bellman cried, As he landed his crew with a thump and a shake. 'Just the place for a Snark! I have sought it for years!'"
}
]
idx = lunr(ref='id', fields=('title', 'body'), documents=documents)
results = idx.search("Alice sister")
for result in results:
print(f"Document Ref: {result['ref']}, Score: {result['score']}")
results_exact = idx.search("+snark -alice")
print(f"\nExact search results for '+snark -alice':")
for result in results_exact:
print(f"Document Ref: {result['ref']}, Score: {result['score']}")
Debug
Known issues
breakingVersion 0.7.0 dropped support for Python 3.6. Users on older Python versions must upgrade to Python 3.7+ or use an earlier Lunr.py version.fixUpgrade Python to 3.7 or newer. Alternatively, pin `lunr<0.7.0`.
affects: >=0.7.0
gotchaThe Lunr.py API is considered in 'alpha stage' and is explicitly stated as 'likely to change' by the maintainers.fixBe prepared for potential API adjustments in future minor or patch releases, and review changelogs carefully during upgrades.
affects: All versions
gotchaUsing the optional `lunr[languages]` feature for non-English stemming relies on NLTK and currently does not guarantee full compatibility with the JavaScript Lunr.js index format or search results.fixTest thoroughly when using language support, especially if interoperability with Lunr.js is a key requirement. Be aware of NLTK corpus licensing.
affects: All versions with `[languages]` extra
gotchaLunr stores its inverted index entirely in memory. For very large document corpuses, this can consume significant RAM and may require recreation or re-reading at each application startup, impacting performance.fixMonitor memory usage with large datasets. Consider pre-building and serializing indexes for client-side consumption (e.g., by Lunr.js) or for faster loading in Python, if applicable.
affects: All versions
Errors
Common errors & fixes
NameError: name 'lunr' is not defined
The `lunr` function, which is the main entry point for creating an index, was not correctly imported from the `lunr` package.
fixEnsure you use `from lunr import lunr` at the top of your script.
TypeError: 'builtin_function_or_method' object is not subscriptable
Attempting to access results from `idx.search()` as if it were a dictionary before iterating over the list of result objects, or calling `lunr` directly with parentheses, which returns the builder function itself.
fixThe `lunr` function is called directly with arguments to create an index: `idx = lunr(...)`. The `idx.search()` method returns a list of dictionaries, so iterate `for result in results:` before accessing `result['ref']` etc.
Unexpected search results (e.g., too many results or missing specific terms)
Misunderstanding the default OR logic of Lunr search queries or incorrect use of term presence modifiers (`+` for required, `-` for prohibited).
fixBy default, Lunr searches with logical OR. To enforce required terms, prefix them with `+` (e.g., `'+term1 term2'`). To prohibit terms, prefix with `-` (e.g., `'term1 -term2'`).
Upgrade
Version history
0.8.0latest on PyPI · released Mar 8, 2025
Audit
Dependencies
nltkoptionalRequired for optional language stemming support.