Install & Compatibility
Where this runs
tested against v2.7.5 · 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
installs and imports cleanly · install 0.0s · import 0.158s · 22MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.146s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
index
✓ from whoosh import index
✗ import whoosh
Importing top-level whoosh doesn't bring index; must import submodules explicitly.
Create an index, add a document, and search.
import os
from whoosh import index
from whoosh.fields import Schema, TEXT
from whoosh.qparser import QueryParser
# Create schema
schema = Schema(title=TEXT(stored=True), content=TEXT)
# Create index directory
os.makedirs('indexdir', exist_ok=True)
ix = index.create_in('indexdir', schema)
writer = ix.writer()
writer.add_document(title=u'First document', content=u'This is the first document we add!')
writer.commit()
# Search
with ix.searcher() as searcher:
query = QueryParser('content', ix.schema).parse('first')
results = searcher.search(query)
print(results[0]['title'])
Debug
Known issues
breakingIn versions 2.7.4.0-2.7.4.4, the import path was 'whoosh_reloaded' instead of 'whoosh'. Upgrade to 2.7.5 to use 'whoosh' again.fixUpgrade to whoosh-reloaded==2.7.5 or change imports from 'whoosh_reloaded' to 'whoosh'.
affects: >=2.7.4.0, <2.7.5
gotchaWhoosh is not thread-safe. The index object and searcher should not be shared across threads without locks.fixUse threading.Lock around index/searcher access or instantiate per-thread.
affects: all
gotchaThe index directory must be locked for writing. If two processes try to write simultaneously, you'll get a LockError.fixUse a single writer per index directory and avoid concurrent writes from multiple processes.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'whoosh'
Using import 'whoosh' when the installed version is old whoosh-reloaded (<2.7.4.4) or the package is not installed.
fixEnsure you have whoosh-reloaded installed (pip install whoosh-reloaded) and import as 'from whoosh import ...'.
whoosh.index.LockError
Trying to create or open an index that is already locked by another process.
fixClose all other writers/searchers or delete the lock file (indexdir/.lock) if no other process is using it.
Upgrade
Version history
2.7.5latest on PyPI · released Feb 2, 2024
Audit
Dependencies
No dependency data recorded yet.