Pagefind Python API

1.5.0 · active · verified Sat Apr 11

Pagefind is a Python API wrapper for the Pagefind Rust binary, providing static, low-bandwidth full-text search capabilities for websites. It excels at indexing large static sites, supporting HTML files, custom records, and multilingual content. The library is actively maintained, with version 1.5.0 released on April 6, 2026, offering an asynchronous interface for programmatic indexing.

Warnings

breaking Pagefind 1.0 (and subsequent versions) changed the default output directory from `_pagefind` to `pagefind`. Existing build scripts or configurations might need updating.
Fix: Update your build process or configuration to expect `pagefind` as the output directory, or explicitly set `output_path` in `IndexConfig`.
breaking Pagefind 1.0 introduced CLI option renames: `source` was renamed to `site`, and `bundle-dir` was renamed to `output-subdir`. This primarily affects direct CLI usage but can impact Python scripts invoking the CLI.
Fix: Adjust any direct CLI calls or subprocess commands to use the new option names (`--site`, `--output-subdir`).
gotcha Installing `pagefind` via `pip install pagefind` only installs the Python wrapper. To get the necessary Pagefind Rust binary automatically, you must install with extras: `pip install 'pagefind[bin]'` for the standard binary, or `pip install 'pagefind[extended]'` for extended language support.
Fix: Always use `pip install 'pagefind[bin]'` or `pip install 'pagefind[extended]'` unless you intend to provide the Pagefind binary yourself.
gotcha The `PagefindIndex` object is an asynchronous context manager and must be used with `async with`. Failing to do so will prevent the index from being properly opened, written, and the backing service shut down.
Fix: Wrap `PagefindIndex` instantiation and usage within an `async with PagefindIndex(...) as index:` block.
behavioral Pagefind v1.1.0 improved its core result ranking algorithm to align with BM25. This change will alter the ordering of search results compared to earlier versions, potentially providing better relevance by default.
Fix: Be aware that search result order may differ. Ranking parameters can be configured via `IndexConfig` if fine-tuning is required.

Install

pip install 'pagefind[bin]' With standard binary
pip install 'pagefind[extended]' With extended binary (Chinese/Japanese support)
pip install pagefind Python wrapper only (requires pre-installed Pagefind binary)

Imports

PagefindIndex

from pagefind.index import PagefindIndex

IndexConfig
```
from pagefind.index import IndexConfig
```

Quickstart

This quickstart demonstrates how to initialize Pagefind, add HTML content directly, and include custom records in the search index using its asynchronous Python API. The output index files will be saved to `./pagefind_output`.

import asyncio
import json
import logging
import os
from pagefind.index import PagefindIndex, IndexConfig

logging.basicConfig(level=os.environ.get("LOG_LEVEL", "INFO"))
log = logging.getLogger(__name__)

html_content = (
    "<html>"
    " <body>"
    " <main>"
    " <h1>Example HTML</h1>"
    " <p>This is an example HTML page.</p>"
    " </main>"
    " </body>"
    "</html>"
)

async def main():
    config = IndexConfig(
        root_selector="main",
        logfile="index.log",
        output_path="./pagefind_output", # Using a custom output path for example
        verbose=True
    )

    async with PagefindIndex(config=config) as index:
        log.debug("Opened index")
        new_file, new_record = await asyncio.gather(
            index.add_html_file(
                content=html_content,
                url="https://example.com/some-page",
                source_path="example.html",
            ),
            index.add_custom_record(
                url="/elephants/",
                content="Some testing content regarding elephants",
                language="en",
                meta={"title": "Elephants"},
            ),
        )

        print(f"Indexed HTML file: {json.dumps(new_file, indent=2)}")
        print(f"Added custom record: {json.dumps(new_record, indent=2)}")

    print("Indexing complete. Output written to ./pagefind_output")

if __name__ == "__main__":
    # To run this, ensure you have installed with `pip install 'pagefind[bin]'`
    # or have the pagefind binary available in your PATH.
    asyncio.run(main())

view raw JSON →