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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.050s · 27.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.042s · 28MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_executable
✓ from pagefind_bin import get_executable
✗ from pagefind_bin import PagefindBinary
get_candidate_paths
✓ from pagefind_bin import get_candidate_paths
cli
✓ from pagefind_bin import cli
This quickstart demonstrates how to install the Pagefind CLI binary using `pagefind-bin`, retrieve its path, and then execute a Pagefind command via `subprocess` to build a search index for a static site. Remember to replace 'my_static_site_output' with your actual static site's build directory.
import os
import subprocess
from pagefind_bin import PagefindBinary
# 1. Initialize and install the Pagefind binary
pagefind = PagefindBinary()
# It's recommended to pin the version for production to avoid unexpected updates:
# pagefind.install(version="1.x.x")
pagefind.install()
# 2. Get the path to the installed binary
pagefind_cli_path = pagefind.path()
print(f"Pagefind CLI installed at: {pagefind_cli_path}")
# 3. Use the Pagefind CLI to build an index (example)
# For this example to work, you'd need some static files in 'my_static_site_output'.
# Replace 'my_static_site_output' with your actual static site build directory.
source_directory = "my_static_site_output" # e.g., 'build', '_site', 'public'
output_directory = os.path.join(source_directory, "pagefind") # Default output dir for Pagefind
# Create a dummy directory and file for demonstration if it doesn't exist
if not os.path.exists(source_directory):
os.makedirs(source_directory, exist_ok=True)
with open(os.path.join(source_directory, "index.html"), "w") as f:
f.write("<html><body><h1>Hello Pagefind!</h1></body></html>")
print(f"Created dummy static site at {source_directory}")
try:
print(f"Running Pagefind build on {source_directory}...")
command = [pagefind_cli_path, "--source", source_directory, "--output", output_directory]
result = subprocess.run(command, capture_output=True, text=True, check=True)
print("Pagefind build successful.")
print("STDOUT:", result.stdout)
if result.stderr:
print("STDERR:", result.stderr)
print(f"Search index generated in {output_directory}")
except subprocess.CalledProcessError as e:
print(f"Pagefind build failed: {e}")
print("STDOUT:", e.stdout)
print("STDERR:", e.stderr)
except FileNotFoundError:
print(f"Error: Pagefind binary not found at {pagefind_cli_path}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
pagefind --version
Debug
Known issues
breakingCalling `PagefindBinary().install()` without a specific `version` argument will download the *latest available* Pagefind CLI binary. This can silently upgrade to a new major version of the Pagefind CLI (e.g., 2.x.x), introducing breaking changes to its command-line arguments, output format, or behavior, even if the `pagefind-bin` Python package version remains stable.fixAlways pin the Pagefind CLI binary version you intend to use in production: `pagefind.install(version='1.x.x')` to prevent unexpected upgrades and ensure consistent behavior.
affects: All `pagefind-bin` versions using `PagefindBinary().install()` without `version`.
gotchaThe `pagefind-bin` library is primarily a wrapper to *install and locate* the Pagefind CLI binary. It does not provide a direct Python API for generating search indexes or running search queries within Python code. Interaction with the core Pagefind functionality must be done by executing the installed binary via `subprocess` or similar methods.fixUtilize Python's `subprocess` module to run the Pagefind binary obtained via `PagefindBinary().path()`, passing required CLI arguments as demonstrated in the quickstart.
affects: All versions
gotchaThe Pagefind CLI binary installed by `pagefind-bin` is typically placed in a project-specific or user-specific directory and is *not automatically added to your system's PATH*. Attempting to run `pagefind` directly in a shell or `subprocess` without specifying the full path will likely result in a 'command not found' error.fixAlways retrieve the full path to the binary using `PagefindBinary().path()` and use this path when executing the command via `subprocess`.
affects: All versions
Upgrade
Version history
1.5.2latest on PyPI · released Apr 12, 2026
Audit
Dependencies
No dependency data recorded yet.