Bottle compatibility precedence across overlapping macOS version ranges

Direct answers

1. Newest compatible bottle? No. Homebrew selects the bottle whose tag exactly matches the normalized current macOS version symbol (e.g., sonoma, ventura). It does not sort by recency or SDK version.

2. Sort order? No SDK-version, architecture-specificity, or checksum sorting occurs during candidate selection. Architecture is resolved before version lookup (only the arm64_*, x86_64_*, or all namespace matching Hardware::CPU.arch is consulted), then a direct key match against the normalized version symbol is performed.

3. Fallback trigger? Source compilation happens only when no bottle entry exists for the current architecture and the normalized macOS version symbol. Overlapping ranges do not cause fallback because the lookup is a hash-key match, not a range intersection.

How the lookup works (Homebrew 4.x)

1. Normalize the running OS. MacOS.version (e.g., 14.5) is mapped to a symbolic name via MacOSVersion.to_sym (14.x → :sonoma, 13.x → :ventura, 15.x → :sequoia).
2. Filter by architecture. The formula's bottle block is split into arm64_*, x86_64_*, and all keys. Only the namespace matching Hardware::CPU.arch (or Rosetta via arch -x86_64 brew / HOMEBREW_FORCE_ARCH=x86_64) is considered.
3. Exact key match. Homebrew looks for a key equal to the normalized symbol (e.g., arm64_sonoma). If present, that bottle is used. If absent, no other key in that namespace is tried — the formula falls back to building from source.

What “overlapping ranges” means in practice

A formula may declare both arm64_ventura and arm64_sonoma. On a Sonoma Mac, only arm64_sonoma is checked; the Ventura bottle is ignored entirely. There is no “closest match” logic. Maintainers control precedence only by ordering keys in the DSL block (earlier duplicate symbols win), but duplicates are rare and discouraged.

Verification steps

# 1. See which tags the formula publishes
brew info --json=v2  | jq '.formulae[0].bottle.tags | keys[]'

# 2. See your normalized version symbol
brew --macos-version   # e.g., 14.5
# Homebrew internally maps 14.x → sonoma

# 3. Watch the exact tag selected (debug log)
HOMEBREW_DEBUG=1 brew install  2>&1 | grep -i pouring
# Output: Pouring --..bottle.tar.gz

# 4. Force fallback to confirm source path
mv ~/Library/Caches/Homebrew/downloads/--..bottle.tar.gz{,.bak}
brew install    # should compile from source

Assumptions & uncertainty

• Behavior described applies to Homebrew 4.x (2024–2025). The BottleSpecification class may change in future major releases.
• Third-party taps sometimes use raw version strings (14.4) instead of symbolic names; Homebrew still performs exact string match after its own normalization.
• Rosetta x86_64 bottles are only consulted when explicitly invoked via arch -x86_64 brew or HOMEBREW_FORCE_ARCH=x86_64.
• Custom HOMEBREW_BOTTLE_DOMAIN mirrors or --bottle-tag overrides affect which file is fetched, not the candidate-selection algorithm.

One diagnostic detail that would change the recommendation

If you are seeing a bottle not matching your normalized version symbol being poured, run HOMEBREW_DEBUG=1 brew install and share the Pouring line. That would indicate either a tap using non-standard tags or a version-normalization bug worth reporting upstream.