Skip to main content

BM25

The easiest way to add powerful search to your Python projects or command line.

💻 GitHub 📦 PyPI 🏠 Homepage

BM25 is a famous algorithm used by search engines (like Elasticsearch) to find the most relevant documents for a given search query. It works by matching keywords and scoring documents based on how often those words appear.

This package provides a dead-simple, beginner-friendly way to use BM25 in Python. Under the hood, it is powered by bm25s, an ultra-fast, highly optimized library. By installing BM25, you get all the performance benefits of bm25s (including speedups and stemming) with a streamlined, 1-line API and a beautiful command-line interface.

🛠️ Installation

Get started in seconds with pip:

pip install BM25

This automatically installs the optimized bm25s backend, along with necessary dependencies for better search quality (PyStemmer) and a colorful terminal experience (rich).

If you want to quickly build a search engine over a local file or a list of texts, the BM25 module makes it incredibly easy.

import BM25

# 1. Load your documents (supports .csv, .json, .jsonl, .txt)
# For csv/jsonl, you can specify which column/key holds the text
corpus = BM25.load("documents.csv", document_column="text")

# 2. Build the search index
retriever = BM25.index(corpus)

# 3. Search!
queries = ["how to learn python", "best search algorithms"]
results = retriever.search(queries, k=5) # Get top 5 results

# Print the top results for the first query
for result in results[0]:
    print(f"Score: {result['score']:.2f} | Document: {result['document']}")

The load function handles reading your files, while index automatically takes care of text processing (tokenization, stemming) and creating the searchable index.

💻 Command-Line Interface (CLI)

Don't want to write code? The BM25 package comes with a built-in terminal app for instant indexing and searching.

Step 1: Index your documents

Turn any text, CSV, or JSON file into a search index.

# Index a simple text file (one document per line)
bm25 index documents.txt -o my_index

# Index a CSV file using a specific column for the text
bm25 index documents.csv -o my_index -c text

Query your newly created index directly from the terminal.

# Basic search (returns top 10 results)
bm25 search -i my_index "what is machine learning?"

# Return more results and save them to a file
bm25 search -i my_index "your query here" -k 20 -s results.json

🌟 Pro-tip: The User Directory

You can save indices to a central user directory (~/.bm25s/indices/) so you can search them from anywhere on your computer without remembering file paths.

# Save to the central directory using the -u flag
bm25 index documents.csv -u -o my_docs

# Search interactively! Just type this, and a menu will let you pick your index:
bm25 search -u "what is AI?"

🚀 Going Further

The BM25 package is designed to be simple and get out of your way. But if you find yourself needing more advanced features—like saving/loading models, integrating with Hugging Face, tweaking the math behind the algorithm, or handling massive millions-of-documents datasets—you already have the tools!

You can drop down to the underlying bm25s library anytime. Check out the bm25s documentation for full details on advanced usage.

Metadata

Release files for BM25 0.3.14

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for BM25 0.3.14
File Size Uploaded Provenance Actions
bm25-0.3.14.tar.gz 6.8 kB With provenance Details for bm25-0.3.14.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for BM25 0.3.14
File Interpreter ABI Platform Actions
bm25-0.3.14-py3-none-any.whl Python 3 none any Details for bm25-0.3.14-py3-none-any.whl

Total release size: 13.1 kB

Release files / bm25-0.3.14.tar.gz

Download URL bm25-0.3.14.tar.gz
Size 6.8 kB
Tags Source
SHA-256 checksum
How to use checksums
1d84e6077671cdbd599ba8141cb4f83d1226c467b294562c4f86ec7525b6872e
BLAKE2b-256 checksum
How to use checksums
8e3d5ef79e5a813a42915eb6304097ce09a5efd96648eb38d4bc469b70a2f401
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

Release files / bm25-0.3.14-py3-none-any.whl

Download URL bm25-0.3.14-py3-none-any.whl
Size 6.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
62d3959972a07c8de5f5d6546bfdfd40c55db402d5bcd5cf7520db68a3fd3bff
BLAKE2b-256 checksum
How to use checksums
b331a3cf2635163c6c5bfe60a83fa93103a72c07345ef5066a16c4dc4dddcbc2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

Security for BM25 0.3.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for bm25-0.3.14.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page