Homebrew Formulae: how the official package browser serves metadata and search

A browser for packages in homebrew-core and homebrew-cask without a terminal

Homebrew Formulae is the website at formulae.brew.sh. It covers two taps: homebrew-core, which holds command-line tools and libraries installable via brew, and homebrew-cask, which holds macOS applications distributed as binary packages. Both appear in a single browsable interface.

For someone who uses the brew command daily, the website offers nothing the CLI cannot. Where it earns its place is for everyone without Homebrew installed: a developer reading a project's dependencies before cloning it, or an ops engineer checking what a package does before adding it to a build image. No terminal is required.

The site also makes analytics data visible. Installation counts and analytics events for packages in both taps appear on each package page, so adoption trends are readable to anyone with a browser rather than only to people querying Homebrew's internal data.

A GitHub Action named tests.yml runs periodically to pull tap changes and deploy

Deployment is automated. When the workflow at .github/workflows/tests.yml runs on its schedule, it reads both homebrew-core and homebrew-cask, rebuilds the site data, and publishes the result to GitHub Pages.

That filename is worth noting: the workflow is described as the deploy mechanism, yet the file is named tests.yml. No explanation for that name appears in the README, and the README makes no mention of a test phase before deployment.

Because the sync runs on a schedule, the site's package data is never exactly current. A formula pushed to homebrew-core today may not appear in the browser until the next scheduled run. No interval for the periodic trigger appears in the README, so the delay between a tap change and its appearance on the site is unquantified. CNAME in the repository root points the custom domain formulae.brew.sh at the Pages host.

The JSON API populates the HTML rather than following from it

The most useful architectural detail in the README: "This JSON data is used for the creation of the HTML resources on this site." The JSON API is not a side feature layered on top of a web frontend; it is the source the site builds from.

Four endpoint types are available. Two operate on the full collection: one lists metadata for all formulae and casks, another lists analytics events across all packages. Two cover individual packages: one returns metadata for a single formula or cask, the other returns its analytics events. Full API documentation lives at formulae.brew.sh/docs/api/.

Any script that needs installation counts or dependency trees for Homebrew packages can query the JSON endpoints and skip HTML parsing, which is exactly what the site itself does. An api/ directory in the repository root holds the endpoint definitions.

Running the site locally: what script/prepare-local-preview.rb actually does

Starting a local copy requires Ruby and Bundler. The README gives the full sequence:

git clone https://github.com/Homebrew/formulae.brew.sh
cd formulae.brew.sh
script/prepare-local-preview.rb
bundle install
bundle exec jekyll serve

Of those five commands, the Ruby script is the one to understand first. Running that script contacts the live API and seeds the local data files; neither a homebrew-core nor a homebrew-cask checkout is needed. A contributor working on templates or layout can start from the cloned repository alone.

Running the prepare script creates a live API dependency. If formulae.brew.sh is unavailable when you run that script, the local preview cannot be seeded. No fallback seeding method is documented, so a contributor working offline, or testing changes against tap data not yet deployed to the API, has no documented path to proceed.

Algolia indexes search, and only brew organisation members control the crawler

Algolia provides search for the site, with a crawler the README names specifically. The README records the crawler's admin URL as https://crawler.algolia.com/admin/crawlers/26b9e6e2-bce4-4f42-9930-6b6ddf06cc9e/overview, adding that the admin panel is "only accessible by brew organisation members."

That restriction closes off direct search tuning for outside contributors. Adding a synonym, adjusting field weights or modifying which fields are indexed all require access to that Algolia dashboard. An outside contributor who wants to change search behavior must propose the change to an existing brew org member. Contributing to the site's Jekyll templates or HTML is open to all, but search configuration is not.

A .vale.ini file appears in the top-level repository entries with no explanation in the README. It is not mentioned in the setup instructions either.

cask-font_index.html is a separate index, not a subsection of cask_index.html

A detail visible in the repository's top-level file listing but absent from the README: three distinct index files exist at the root. formula_index.html and cask_index.html are expected from a browser covering two taps. A third file, cask-font_index.html, gets its own dedicated page.

The README describes the site as displaying "all packages in... homebrew-core and... homebrew-cask" without acknowledging that font casks are separated from regular casks at the page level. Homebrew fonts are casks that install typefaces. Treating them as a distinct index rather than a subset of cask_index.html is a navigation decision visible only in the file structure.

Anyone building a tool that mirrors the site's structure, or a script that walks all index pages, must account for three index files rather than two. That distinction does not appear in the README.

What the site does not cover: private taps and real-time tap state

Homebrew Formulae covers exactly two repositories: homebrew-core and homebrew-cask. A team maintaining a private tap, or a third-party tap not included in either, cannot use this browser or its JSON API to expose their packages. No configuration option in the repository supports pointing the site at a different tap.

Real-time state is also outside what the project provides. The API exposes what the last periodic deploy committed. A script querying the API immediately after a formula update in homebrew-core will get the previous version until the next scheduled GitHub Action run.

For contributors, Gemfile.lock in the repository pins gem versions. Running bundle install against that lock file installs a specific environment rather than the latest available versions of each dependency, which aids reproducibility but requires attention when upgrading gems. Code in the repository is under the BSD-2-Clause license, and the last push was on 2026-10-02.

Editorial conclusion

Use the website at formulae.brew.sh directly to browse packages or read analytics. Run a local copy if you contribute to the site's layout, templates or scripts, keeping in mind that the prepare script fetches live API data and will fail offline. For programmatic access to package metadata or download analytics, the JSON API at formulae.brew.sh is the documented path. If you need real-time package state rather than periodically synced data, the API is the wrong layer to query, because updates from the taps arrive only after the GitHub Action runs.

Frequently asked questions

Official sources

1. Homebrew/formulae.brew.sh on GitHub
2. Issues
3. License: BSD-2-Clause
4. Project website
5. README