Whoosh-NG Documentation

Latest release: v5.1.0 | View releases on GitHub | Last updated: 2026-08-12

Welcome to the official documentation for Whoosh-NG, a pure-Python full-text indexing and search library modernized for 2025+.

Language Selection

This documentation is available in two languages:

• English Documentation — Complete technical documentation in English (source language)
• Documentation Française — Traduction française complète

Both versions are kept synchronized, with code examples remaining in English for consistency.

Documentation Structure

Core (Classic Whoosh)

• Quick Start — 5-minute tutorial
• Installation — Setup instructions
• Core Concepts — Schemas, fields, search
• Indexing — Adding and updating documents
• Searching — Query parsing and results
• Schema Design — Field types and storage
• Query Language — Lucene-like query syntax
• Backends — File, SQLite, memory storage
• Dates — Date field handling
• Nested Documents — Nested document support
• Glossary — Key terms and definitions
• Migration — Migrating from classic Whoosh
• Legacy Cleanup — Legacy code removal
• Translation Status — i18n progress

Modern (New Features)

• Middleware — Pipeline hooks and middleware
• Middleware & Plugin Pipeline — Hook-based pipeline
• Plugins — Extending Whoosh-NG
• Plugin System — PluginManager API
• Autocomplete — Autocomplete providers
• Autocomplete Providers — NGram, Fuzzy, InvertedIndex
• Vector Search — NumPy, HNSW, Faiss
• Modern Indexing — BatchIndexWriter, AnalyzerCache
• Monitoring — Metrics and observability
• Performance — Benchmarking and optimization
• Linguistics & Synonyms — SynonymManager
• Stemming — Language stemmers
• Stemmer Providers — PyStemmer backends
• N-grams — N-gram tokenization
• Storage Providers — Hybrid storage backends
• Provider Integration — Complete pipeline guide for all providers

API Reference

• API Overview — Complete module reference
• Core API — Index creation and management
• Fields — Schema and field type definitions
• Analysis — Tokenizers, filters, and analyzers
• Highlight — Formatters, fragmenters, scorers
• Spelling — Spell checking and query correction
• Sorting — Facets and sort key computation
• Collectors — Result collection strategies
• Reading — Index readers and term vectors
• Matching — Matcher classes and utilities
• Codecs — Index format codecs and segment management
• Formats — Posting format encoders/decoders
• Columns — Per-document column storage
• Idsets — Document ID set implementations
• Automata — Finite state automata and FSTs
• Classify — Query expansion and clustering
• Language — Stemmers, stop words, and language utilities
• File DB / Storage — Storage and file I/O
• Writing API — IndexWriter interface
• Searching API — Searcher and Results
• Query API — Query classes and parsers
• Events — Event bus system
• Middleware API — Middleware pipeline
• Plugins API — Plugin system and registry
• Backends API — Storage backend abstractions
• Modern API — Modern extensions

Examples

• Basic Indexing — Document indexing examples
• Search Examples — Querying and retrieving results
• Search Models — Auto-mapping Python models to Whoosh schemas
• FastAPI Integration — REST API with FastAPI
• Middleware Examples — Custom middleware patterns
• Middleware Pipeline — Retry, cache, logging
• Movie Search App — Complete movie search application
• Plugin Development — Building plugins
• Data Sources — SQLSource, RESTSource, GraphQLSource, FastCSVSource, JSONSource, ParquetSource, PandasSource, PolarsSource, SQLAlchemySource, PeeweeSource, TortoiseSource
• Schema Discovery — Result-set introspection
• Facet Manager — Auto-discovery and manual overrides
• Validation Framework — 4-level validation
• SearchView — Full pipeline integration
• Autocomplete — Autocomplete provider examples
• Vector Search — NumPy, HNSW, and Faiss integrations

Quick Overview

Whoosh-NG combines classic Whoosh's pure-Python full-text search with modern features:

• Pure Python — No native dependencies, works anywhere Python runs
• Embedded search engine — No separate server required
• Plugin architecture — Extensible with vector search, autocomplete, and more
• Middleware pipeline — Cross-cutting concerns like metrics, caching, encryption
• Vector search support — NumPy, HNSW, and Faiss integrations
• Async support — Optional async/await support via extras

Quick Links

• Project Repository: GitHub - whoosh-ng
• PyPI Package: whoosh-ng
• Issue Tracker: GitHub Issues
• LLM-Friendly Docs:
  • llms.txt — Index of all documentation pages
  • llms-full.txt — Complete API documentation concatenated

Contributing

Contributions are welcome! Please read our contributing guide for details on how to submit pull requests, add features, or report bugs.

License

This project is licensed under the MIT License.