{"id":3204,"library":"pagefind-bin","title":"Pagefind","description":"Pagefind is a library for performant, low-bandwidth, fully static search. The `pagefind-bin` Python package provides a convenient wrapper to install and manage the Pagefind binary for use in Python projects, making its CLI tools accessible. The current version is 1.5.0, and it typically releases updates in sync with the upstream Pagefind binary releases.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/jh-squared/pagefind-bin","tags":["search","static-site","full-text-search","binary-wrapper","cli-tool"],"install":[{"cmd":"pip install pagefind-bin","lang":"bash","label":"Install the pagefind-bin package"}],"dependencies":[],"imports":[{"note":"The primary interaction is with the PagefindBinary class to install and locate the Pagefind CLI tool.","symbol":"PagefindBinary","correct":"from pagefind_bin import PagefindBinary"}],"quickstart":{"code":"import os\nimport subprocess\nfrom pagefind_bin import PagefindBinary\n\n# 1. Initialize and install the Pagefind binary\npagefind = PagefindBinary()\n# It's recommended to pin the version for production to avoid unexpected updates:\n# pagefind.install(version=\"1.x.x\")\npagefind.install()\n\n# 2. Get the path to the installed binary\npagefind_cli_path = pagefind.path()\nprint(f\"Pagefind CLI installed at: {pagefind_cli_path}\")\n\n# 3. Use the Pagefind CLI to build an index (example)\n# For this example to work, you'd need some static files in 'my_static_site_output'.\n# Replace 'my_static_site_output' with your actual static site build directory.\nsource_directory = \"my_static_site_output\" # e.g., 'build', '_site', 'public'\noutput_directory = os.path.join(source_directory, \"pagefind\") # Default output dir for Pagefind\n\n# Create a dummy directory and file for demonstration if it doesn't exist\nif not os.path.exists(source_directory):\n os.makedirs(source_directory, exist_ok=True)\n with open(os.path.join(source_directory, \"index.html\"), \"w\") as f:\n f.write(\"

Hello Pagefind!

\")\n print(f\"Created dummy static site at {source_directory}\")\n\ntry:\n print(f\"Running Pagefind build on {source_directory}...\")\n command = [pagefind_cli_path, \"--source\", source_directory, \"--output\", output_directory]\n result = subprocess.run(command, capture_output=True, text=True, check=True)\n print(\"Pagefind build successful.\")\n print(\"STDOUT:\", result.stdout)\n if result.stderr:\n print(\"STDERR:\", result.stderr)\n print(f\"Search index generated in {output_directory}\")\nexcept subprocess.CalledProcessError as e:\n print(f\"Pagefind build failed: {e}\")\n print(\"STDOUT:\", e.stdout)\n print(\"STDERR:\", e.stderr)\nexcept FileNotFoundError:\n print(f\"Error: Pagefind binary not found at {pagefind_cli_path}\")\nexcept Exception as e:\n print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always 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.","message":"Calling `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.","severity":"breaking","affected_versions":"All `pagefind-bin` versions using `PagefindBinary().install()` without `version`."},{"fix":"Utilize Python's `subprocess` module to run the Pagefind binary obtained via `PagefindBinary().path()`, passing required CLI arguments as demonstrated in the quickstart.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always retrieve the full path to the binary using `PagefindBinary().path()` and use this path when executing the command via `subprocess`.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}