Why Homebrew sometimes compiles from source instead of using a bottle

The install that takes twenty minutes

You run brew install ffmpeg expecting a quick download, but Homebrew starts compiling from source instead. Your terminal fills with compiler output, and you wait. This happens because Homebrew could not use a prebuilt bottle—Homebrew’s term for a precompiled binary package—and fell back to building the software on your machine.

The useful takeaway: bottle fallback is usually a compatibility or availability issue, not a bug. You can check whether a bottle exists for your system before you install, and you can decide whether to wait for the source build or look for an alternative.

What a bottle contains

A Homebrew formula is a Ruby script that describes how to install a piece of software. A bottle is the precompiled result of that formula. It bundles the built binaries along with metadata: the target macOS version, CPU architecture (Intel or Apple silicon), dependency versions, and a checksum that Homebrew uses to verify the download.

When you install a formula, Homebrew downloads the matching bottle, verifies its checksum against your local system profile, and unpacks it. If no bottle matches your operating system version, architecture, or dependency set, Homebrew compiles from source instead.

Why Homebrew skips the bottle

Bottle installation is skipped or fails for a few common reasons:

• No bottle was published. New or infrequently updated formulae may only have source builds available.
• Architecture mismatch. A bottle built for Intel Macs will not install on Apple silicon, and vice versa, unless it is a fat universal binary.
• macOS version mismatch. Bottles are built against specific SDK and library versions. If your system is significantly older or newer than the build environment, the checksum or dependency check can fail.
• Local modifications. If you passed build options or changed environment variables, Homebrew may disregard the bottle and compile from source to honor your configuration.

Worked example: check before you install

Run this in Terminal as a normal user. Homebrew does not require sudo for standard operations.

brew info --formula --json=v2 ffmpeg

Look for the bottle key in the JSON output. If it is present and includes a stable tag for your architecture and macOS version, Homebrew should use the bottle. If the key is absent, or if the available bottles list only architectures you do not have, Homebrew will compile from source.

You can also inspect your current build environment:

brew config

Check the CPU, OS, and CLT (Command Line Tools) fields. A missing or outdated CLT can force source compilation even when a bottle exists, because Homebrew needs a compiler toolchain to verify or relink some packages.

To force a source build intentionally, use:

brew install --build-from-source ffmpeg

Risk: source compilation can take several minutes to over an hour for large projects, and it requires the Xcode Command Line Tools to be installed.

Trade-off: convenience versus control

Bottles save time and reduce local build dependencies, but they are built by Homebrew maintainers on their own machines. If you need non-default compile flags, a patched version, or a build optimized for your specific CPU microarchitecture, source compilation gives you that control at the cost of time. For most users, the bottle is the right default; treat source builds as an opt-in fallback.

What to check next

Before you start a long compile, run brew info --formula --json=v2 <formula> and confirm that a bottle exists for your brew config CPU and OS values. If no bottle matches, you can proceed with --build-from-source, search for a different formula, or wait for maintainers to publish a bottle. There is no rollback step here because checking metadata does not change system state.