pagefind

library1.5.2pypypi✓ verified 24d ago

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.

web-framework

pip install 'pagefind[bin]'

package ↗homepage ↗

INSTALL

IMPORT

SIG · PAGEFIND

pagefind

web-frameworkpythonv1.5.2

Install

1.9s avg

Import

222ms

Disk

72MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.2 · 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

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 0.233s · 74MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 1.9s · import 0.210s · 74MB

72MB installed

● package 72MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PagefindIndex

✓ from pagefind.index import PagefindIndex

IndexConfig

✓ from pagefind.index import IndexConfig

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())

Debug

Known issues

breakingPagefind 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`.

affects: >=1.0.0

breakingPagefind 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`).

affects: >=1.0.0

gotchaInstalling `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.

affects: All versions

gotchaThe `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.

affects: All versions

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

affects: >=1.1.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pagefind'

The 'pagefind' Python package has not been installed or is not accessible in the current Python environment.

fix

Install the package using pip: `python3 -m pip install 'pagefind[extended]'` or `python3 -m pip install 'pagefind[bin]'`.

pagefind: command not found

The 'pagefind' executable (the underlying Rust binary) is not in the system's PATH, or the user is attempting to run the command directly instead of through the Python wrapper or `npx`.

fix

If installed via the Python package, run it using `python3 -m pagefind --site public`. If installed via npm, use `npx pagefind --site public`. If manually downloaded, ensure the binary's directory is in your system's PATH.

AttributeError: module 'pagefind' has no attribute 'index'

The user is attempting to access an 'index' attribute directly on the top-level 'pagefind' module, but the indexing functionality is located within the `pagefind.index` submodule and accessed via the `PagefindIndex` class.

fix

Import the `PagefindIndex` class from `pagefind.index` and then instantiate it: `from pagefind.index import PagefindIndex` followed by `indexer = PagefindIndex()`.

Upgrade

Version history

1.5.2latest on PyPI · released Apr 12, 2026

Audit

Dependencies

pythonrequiredRuntime dependency

pagefind (Rust binary)requiredCore indexing engine, bundled via extras or requires manual installation

Agent activity

12 hits · last 30 days

node

Amazon

Resources

packagehttps://pypi.org/project/pagefind/ ↗

homepagehttps://pagefind.app ↗