Install & Compatibility
Where this runs
tested against v2.7.4 · 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.166s · 21.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.150s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_in
✓ from whoosh.index import create_in
Schema
✓ from whoosh.fields import Schema, TEXT, ID, STORED
QueryParser
✓ from whoosh.qparser import QueryParser
index
✓ from whoosh import index
✗ import whoosh.index
While 'import whoosh.index' works, direct import from whoosh.index is more common for specific functions like create_in or open_dir, and 'from whoosh import index' is used to access general index-related functions and objects.
This quickstart demonstrates how to define a schema, create or open an index, add documents to the index, and then perform a basic text search. It includes handling the creation of the index directory if it doesn't exist. Documents are added with `title`, `path`, and `content` fields, and a `QueryParser` is used to search the 'content' field.
import os
from whoosh.index import create_in, open_dir
from whoosh.fields import Schema, TEXT, ID
from whoosh.qparser import QueryParser
# 1. Define schema
schema = Schema(title=TEXT(stored=True), path=ID(stored=True), content=TEXT)
# 2. Create or open index directory
indexdir = "indexdir"
if not os.path.exists(indexdir):
os.mkdir(indexdir)
ix = create_in(indexdir, schema)
else:
ix = open_dir(indexdir)
# 3. Add documents
writer = ix.writer()
writer.add_document(title=u"First document", path=u"/a",
content=u"This is the first document we've added!")
writer.add_document(title=u"Second document", path=u"/b",
content=u"The second one is even more interesting!")
writer.commit()
# 4. Search documents
with ix.searcher() as searcher:
query_parser = QueryParser("content", ix.schema)
query = query_parser.parse("first")
results = searcher.search(query)
for hit in results:
print(f"Found: {hit['title']} at {hit['path']}")
# Clean up (optional: remove the index directory)
# import shutil
# shutil.rmtree(indexdir)
whoosh --version
Debug
Known issues
gotchaWhen adding documents, ensure text fields are passed as Unicode strings (e.g., `u"my text"` in Python 2 or regular strings in Python 3). Non-text fields that are stored but not indexed (STORED type) can be any pickle-able object.fixPrefix string literals with 'u' in Python 2 (e.g., `u'your string'`). In Python 3, all strings are Unicode by default, so `"your string"` is sufficient.
affects: All versions
gotchaWhoosh does not inherently enforce uniqueness for documents. Calling `add_document` multiple times with identical data will result in multiple duplicate documents in the index. Use `update_document` with a `unique=True` field in your schema to overwrite existing documents.fixDefine a unique field in your Schema (e.g., `path=ID(unique=True)`), then use `writer.update_document()` instead of `writer.add_document()` when you intend to replace or update an existing document. If no match is found for the unique field, `update_document` acts like `add_document`.
affects: All versions
gotchaThe `whoosh.index.create_in()` function requires the directory to exist before it's called. If the directory does not exist, a `FileNotFoundError` will occur.fixAlways ensure the directory for your index exists by creating it with `os.makedirs(indexdir, exist_ok=True)` or `os.mkdir(indexdir)` before calling `create_in()`.
affects: All versions
deprecatedDirect manipulation of index files or relying on undocumented internal structures can lead to issues with future updates. Always use the public API for index management. Some older examples might show direct `FileStorage` usage without `index.create_in` or `index.open_dir` convenience functions.fixStick to high-level functions like `whoosh.index.create_in()` and `whoosh.index.open_dir()` for managing your index to ensure compatibility and stability.
affects: <2.x (informal deprecation, more of a best practice)
Errors
Common errors & fixes
whoosh.index.AlreadyLockedError: Locked by '<pid>'
An `IndexWriter` object was not properly closed, or multiple processes/threads are attempting to write to the index simultaneously, leaving a stale lock file.
fixEnsure `IndexWriter` objects are always closed using a `with` statement. If a stale lock persists, it might need to be manually deleted (e.g., `os.remove('path/to/index/MAIN_WRITELOCK')`).
```python
# Correct usage using a 'with' statement
with ix.writer() as writer:
writer.add_document(title='Example', content='Document content')
# Or, for explicit control
writer = ix.writer()
try:
writer.add_document(title='Example', content='Document content')
writer.commit()
finally:
writer.close()
``` AttributeError: module 'whoosh' has no attribute 'Schema'
The `Schema` class (and many other core Whoosh components like `create_in`, `QueryParser`) is not directly available under the top-level `whoosh` module; it resides in a specific submodule.
fixImport the class from its correct submodule, for example, `Schema` from `whoosh.fields`, `create_in` from `whoosh.index`, and `QueryParser` from `whoosh.qparser`.
```python
from whoosh.fields import Schema, TEXT, ID
from whoosh.index import create_in, open_dir
from whoosh.qparser import QueryParser
```
OSError: [Errno 2] No such file or directory: 'path/to/index/_MAIN_0.toc'
The directory specified for creating or opening the Whoosh index does not exist, or the path is incorrect.
fixEnsure the index directory exists before attempting to create or open an index, creating it if necessary.
```python
import os
from whoosh.index import create_in
from whoosh.fields import Schema, TEXT
index_dir = "my_whoosh_index"
if not os.path.exists(index_dir):
os.makedirs(index_dir)
schema = Schema(title=TEXT(stored=True), content=TEXT)
ix = create_in(index_dir, schema)
``` whoosh.query.qcore.QueryError: Not enough arguments for QueryParser
The `QueryParser` was instantiated without a schema or a default field, or an empty/invalid query string was passed to its `parse()` method.
fixEnsure `QueryParser` is initialized with a schema and a default field, and always pass a non-empty, valid query string to its `parse()` method.
```python
from whoosh.qparser import QueryParser
from whoosh.fields import Schema, TEXT
my_schema = Schema(title=TEXT(stored=True), content=TEXT(stored=True))
# Initialize QueryParser with a default field and the schema
qp = QueryParser("content", schema=my_schema)
# Ensure the query string is not empty or invalid
query_string = "search term"
if query_string:
my_query = qp.parse(query_string)
``` Upgrade
Version history
2.7.4latest on PyPI · released Apr 4, 2016
Audit
Dependencies
No dependency data recorded yet.