carapace-sh/carapace-bin / skills/brew
brew
VerifiedUse when working with Homebrew (`brew`) — the package manager for macOS and Linux. Covers the command structure, formula and cask DSLs, taps, bottles, the Cellar, services, bundle/Brewfile, environment variables, installation internals, and developer commands. Triggers on: "brew", "homebrew", "brew install", "brew uninstall", "brew update", "brew upgrade", "brew search", "brew tap", "brew cask", "brew bottle", "brew services", "brew bundle", "brew cleanup", "brew doctor", "brew audit", "brew livecheck", "brew test-bot", "brew bump-formula-pr", "Brewfile", "HOMEBREW_PREFIX", "HOMEBREW_CELLAR", "HOMEBREW_NO_INSTALL_FROM_API", "HOMEBREW_CASK_OPTS", "HOMEBREW_BOTTLE_DOMAIN", "Formula", "Cask", "Cellar", "Caskroom", "keg", "rack", "tap", "bottle", "superenv", "Formulary", "FormulaInstaller", "shellenv", "restart_service", "keg-only", "brew deps", "brew uses", "brew leaves", "brew outdated", "brew pin", "brew fetch", "brew create", "brew edit", "livecheck", "auto_updates", "depends_on".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.8 KB |
| references/bottle.md | markdown | 5.3 KB |
| references/bundle.md | markdown | 9.1 KB |
| references/cask.md | markdown | 13.0 KB |
| references/cellar.md | markdown | 7.2 KB |
| references/commands.md | markdown | 11.7 KB |
| references/dependency.md | markdown | 3.9 KB |
| references/developer.md | markdown | 13.2 KB |
| references/environment.md | markdown | 11.8 KB |
| references/formula.md | markdown | 11.8 KB |
| references/maintenance.md | markdown | 5.9 KB |
| references/services.md | markdown | 6.9 KB |
| references/taps.md | markdown | 5.1 KB |
references/bottle.md
View on GitHub# Bottles
Bottles are pre-built binary packages that Homebrew "pours" into the Cellar instead of building from source. This document covers the bottle DSL, the `brew bottle` command, pouring, relocation, and related commands.
## How Bottles Work
When running `brew install`, Homebrew checks if a bottle exists for the user's specific macOS version and CPU architecture. If so, it "pours" the bottle (extracts the archive) into the Cellar. Otherwise, it builds from source.
```
brew install <formula>
→ Check for matching bottle tag
→ Bottle exists? → Pour (extract) into Cellar → Link
→ No bottle? → Build from source → Link
```
### Bottle Naming Convention
```
formula--version.os.bottle.tar.gz
```
Examples:
```
foo--0.1.ventura.bottle.tar.gz
qt--6.5.1.ventura.bottle.tar.gz
foo--0.1.arm64_ventura.bottle.tar.gz
```
Bottle tags encode OS and architecture: `ventura`, `arm64_ventura`, `sonoma`, `x86_64_linux`, etc.
### Bottle Hosting
Bottles for `homebrew/core` are hosted on GitHub Container Registry at `https://ghcr.io/v2/homebrew/core`. The bottle domain can be changed with `HOMEBREW_BOTTLE_DOMAIN`.
## Bottle DSL in Formulae
The `bottle` block in a formula defines pre-built binary packages. It is managed by `BottleSpecification`.
```ruby
bottle do
root_url "https://ghcr.io/v2/homebrew/core"
sha256 cellar: :any_skip_relocation, arm64_sonoma: "abc123..."
sha256 cellar: :any_skip_relocation, arm64_ventura: "def456..."
sha256 cellar: :any_skip_relocation, sonoma: "ghi789..."
sha256 cellar: :any_skip_relocation, ventura: "jkl012..."
sha256 cellar: :any_skip_relocation, x86_64_linux: "mno345..."
end
```
### `cellar` Values
| Value | Meaning |
|-------|---------|
| `:any` | Bottle can be used regardless of Cellar location |
| `:any_skip_relocation` | Bottle can be used anywhere; no relocation needed |
| _(path)_ | Bottle must be poured into a specific Cellar path |
## Pouring and Relocation
When a bottle is poured into a non-default prefix, Homebrew performs **binary relocation** to fix hardcoded paths:
- Replaces the build-time `HOMEBREW_PREFIX` with the user's actual prefix
- Updates `install_name`/`rpath` entries in Mach-O binaries (macOS)
- Updates `RUNPATH` entries in ELF binaries (Linux)
The `--skip-relocation` flag to `brew bottle` marks bottles as not needing relocation (`:any_skip_relocation`).
## `brew bottle` Command
Generates a bottle from a formula built with `--build-bottle`.
```bash
brew install --build-bottle foo
brew bottle foo
```
| Flag | Purpose |
|------|---------|
| `--skip-relocation` | Mark bottle as not needing relocation |
| `--force-core-tap` | Bottle even if not from core tap |
| `--no-rebuild` | Don't add rebuild version |
| `--keep-old` | Keep old bottle block entries |
| `--json` | Write JSON metadata |
| `--merge` | Merge JSON from multiple platforms |
| `--write` | Write bottle block to formula |
| `--no-commit` | Don't commit changes |
| `--only-json-tab` | Only write JSON tab (no INSTALL_RECEIPT) |
| `--no-all-checks` | Don't create an `all` bottle or stop a no-change upload (requires `--merge`) |
| `--root-url <url>` | Override root URL |
| `--root-url-using <strategy>` | Download strategy for root URL |
### Workflow
```
brew install --build-bottle <formula> # Build with bottle preparation
brew bottle <formula> # Generate bottle + JSON
# ... on multiple platforms ...
brew bottle --merge --write *.json # Merge and write bottle block
```
## `brew unbottled`
Shows formulae that lack bottles for a given tag, and their dependents.
| Flag | Purpose |
|------|---------|
| `--tag <tag>` | Specific bottle tag |
| `--dependents` | Show dependents of unbottled formulae |
| `--total` | Show total counts |
| `--lost` | Print `homebrew/core` commits where bottles were lost in the last week |
## `brew verify`
Verifies bottle build provenance using GitHub attestations (requires `gh` CLI).
| Flag | Purpose |
|------|---------|
| `--os <os>` / `--arch <arch>` | Target platform |
| `--bottle-tag <tag>` | Specific bottle tag |
| `--deps` | Verify all dependencies too |
| `-f, --force` | Force re-verification |
| `-j, --json` | JSON output |
Related environment variables:
| Variable | Purpose |
|----------|---------|
| `HOMEBREW_VERIFY_ATTESTATIONS` | Enable verification |
| `HOMEBREW_NO_VERIFY_ATTESTATIONS` | Disable verification |
## Related Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| `HOMEBREW_BOTTLE_DOMAIN` | `https://ghcr.io/v2/homebrew/core` | Bottle download mirror URL |
| `HOMEBREW_ARTIFACT_DOMAIN` | — | Prefix all download URLs (mirror) |
| `HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK` | — | Error instead of fallback when artifact domain fails |
| `HOMEBREW_GITHUB_PACKAGES_TOKEN` | — | GitHub Packages auth token |
| `HOMEBREW_GITHUB_PACKAGES_USER` | — | GitHub Packages username |
| `HOMEBREW_DOCKER_REGISTRY_TOKEN` | — | Docker registry bearer token |
| `HOMEBREW_DOCKER_REGISTRY_BASIC_AUTH_TOKEN` | — | Docker registry basic auth |
## References
- [Bottle documentation](https://docs.brew.sh/Bottles)
- For formula DSL: [formula.md](formula.md)
- For the Cellar: [cellar.md](cellar.md)
- For environment variables: [environment.md](environment.md)
- For developer commands: [developer.md](developer.md)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |