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.15

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.15
File Size Uploaded Provenance Actions
bm25-0.3.15.tar.gz 6.8 kB With provenance Details for bm25-0.3.15.tar.gz

Built distribution (wheel)

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

Total release size: 13.1 kB

Release files / bm25-0.3.15.tar.gz

Download URL bm25-0.3.15.tar.gz
Size 6.8 kB
Tags Source
SHA-256 checksum
How to use checksums
bbcf6f1d322d7fa39308355db652ee11fdd30147ab2c028e741ce214ab094106
BLAKE2b-256 checksum
How to use checksums
afa48f88644071d7c1c48a206ef96d1f8e253c18e8b8b8825451e098363a49af
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 22, 2026.

Transparency log

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

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

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 22, 2026.

Transparency log

Security for BM25 0.3.15

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.15.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 22, 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