Homebrew Bottles: Architecture Note for Binary Distribution and Trust Boundaries

The problem you are solving

You need the same formula installed quickly and identically on many macOS and Linux machines without triggering a source compile on each host. Homebrew solves this with bottles: pre-compiled package archives stored per formula-version-platform, with deterministic metadata that lets mirrors, caches and automation decide whether a binary install is safe.

The useful takeaway is that a bottle is not just a tarball. It is a platform triple bound artifact plus a JSON descriptor and optional per-bottle caveats. If you design automation around that triple and the descriptor, you get reproducible installs. If you design around file names or assumptions about URLs, you break on platform gaps or Homebrew changes.

Requirements that drive the design

Binary compatibility must be explicit. A bottle is tagged with an operating system, OS version and architecture. Homebrew calls this a platform triple. Without it, a binary built for macOS arm64 would be offered to Intel Linux.

Distribution must be cacheable and mirrorable. Bottle URLs follow a stable pattern under /Formula////.json. The JSON points to the tarball and contains checksums and caveats. That separation lets you mirror the JSON and the tarball independently and verify integrity without compiling.

Post-install differences must not require formula edits. Per-bottle caveats allow platform-specific commands such as linking or environment variable hints without changing the Ruby formula source. This keeps the formula portable while the bottle carries the local adaptation.

Trust must be verifiable at install time. The bottle JSON is the trust anchor for a given platform. Homebrew verifies the tarball against the checksums in the JSON before extracting into the Cellar.

Smallest suitable design

The minimal working set is three artifacts per formula version per platform:

• Formula Ruby file in homebrew-core defining build steps and dependencies.
• Bottle JSON descriptor with url, sha256, cellar path and caveats for the platform triple.
• Bottle tarball containing the pre-built prefix tree for that triple.

On install, Homebrew resolves the current platform triple, selects the matching bottle JSON, verifies the tarball, extracts to Cellar//, and runs the caveats if present. No source is touched when a matching bottle exists.

A concrete decision point is whether to allow a source fallback. The smallest design keeps fallback explicit: if the Bottle section is empty for your triple, Homebrew falls back to building from source. That is a feature, not a failure, but it changes install time and reproducibility guarantees.

Trust and data boundaries

Boundary 1: homebrew-core repository vs mirrors. The formula and bottle JSON are authoritative in core. Mirrors replicate them. Automation that parses URLs should treat the JSON as the source of truth, not the tarball path.

Boundary 2: Homebrew client vs Cellar. The client writes to Cellar under the user’s Homebrew prefix. Bottle extraction is user-scoped and does not require elevated permissions on macOS, but Linux installs may need write access to /home/linuxbrew/.linuxbrew.

Boundary 3: formula author vs bottle builder. The formula defines what to build. The bottle builder produces the artifact for a specific triple. Per-bottle caveats are authored with the bottle, not the formula, preventing cross-platform side effects.

Operational checks

Check bottle relevance before relying on binary install. Run locally as the user who will install:

brew info <formula>

Inspect the Bottle section for a URL matching your platform triple. A missing entry means source-only for that triple.

To compare descriptor fields against your environment without building:

brew bottle <formula>

Run this on a machine with the formula installed. It outputs JSON with url and caveats fields. Compare the platform fields in the JSON to your OS and architecture. This is a read-only check; generating a new bottle requires write access to the formula and may trigger a build.

Risk: running brew bottle on a production host can start a build if no bottle exists. Use --json and run on a representative build host instead.

Failure modes

Bottle availability gaps. Formulae without pre-built binaries for a platform force source compilation. This increases install time and introduces variability from compiler versions and dependencies.

Platform mismatch. Using a bottle built for a different OS version or architecture leads to runtime failures. The triple check prevents this, but scripts that hard-code URLs bypass the check.

URL schema drift. Homebrew version upgrades can change bottle URL structures. Automation that parses paths breaks. Depend on brew info and the JSON descriptor rather than string parsing.

Signature or checksum mismatch. A corrupted mirror or partial download fails verification. Homebrew will abort extraction. Do not disable verification to work around this.

Caveats not applied. Per-bottle caveats are printed after install. If your workflow requires environment variables or symlinks, ensure the caveats are captured and applied in your provisioning scripts.

When the design would change

If you need per-user customization inside the binary prefix, bottles are the wrong primitive. Bottles are immutable per triple. Custom patches require a tap formula or a post-install wrapper.

If you need guaranteed availability for all platforms, you must build and publish bottles for each triple you support. That shifts cost from install time to CI build time and storage.

If you need reproducible builds across Homebrew major versions, pin the Homebrew client version in your environment and validate bottle JSON schemas after upgrades. Schema changes are a known condition for breaking automation.

Limitations to keep in mind: bottles do not capture host-specific state such as kernel extensions or system libraries outside the prefix. Verify the result after install by checking the installed prefix exists under Cellar and the caveats output matches expectations for your platform.