Skip to main content
By default, zerobrew installs pre-built bottles (binary packages) from Homebrew’s infrastructure for maximum speed. However, you can build packages from source when needed using the --build-from-source flag.

​
When to Build from Source

Consider building from source when:
  • Pre-built bottles are unavailable for your platform
  • You need custom compilation flags or optimizations
  • You’re debugging package issues
  • You want packages optimized for your specific CPU architecture
  • A bottle is corrupted or outdated
Building from source is significantly slower than installing bottles. A package that installs in seconds from a bottle may take minutes to build from source.

​
Basic Usage

Use the -s or --build-from-source flag with zb install: 
zb install jq --build-from-source
zb install jq -s
Output: 
==> Installing jq...
==> Resolving dependencies (1 packages)...
    jq 1.7.1
==> Downloading and installing formulas...
    jq              ⠋ building from source...

​
Installing Multiple Packages from Source

Build all specified packages from source: 
zb install wget git sqlite --build-from-source
This builds wget, git, and sqlite from source, along with any dependencies.

​
How Source Builds Work

When you use --build-from-source, zerobrew:
  1. Downloads the formula definition from homebrew-core
  2. Fetches the source tarball or repository
  3. Compiles the package using Homebrew’s Ruby DSL build instructions
  4. Installs to zerobrew’s content-addressable store
  5. Links binaries to your prefix (unless --no-link is used)

​
Build Requirements

Building from source requires:
  • Compiler toolchain: Xcode Command Line Tools (macOS) or build-essential (Linux)
  • Ruby: For executing Homebrew formula build scripts
  • Dependencies: Any build-time dependencies the package requires

​
Installing build tools on macOS

xcode-select --install

​
Installing build tools on Linux

# Debian/Ubuntu
sudo apt-get install build-essential

# Fedora/RHEL
sudo dnf groupinstall "Development Tools"

​
Combining with Other Flags

​
Build from source without linking

zb install ffmpeg --build-from-source --no-link
This builds ffmpeg from source but doesn’t add it to your PATH.

​
Build and install in one command

zb install ripgrep -s && ripgrep --version

​
Performance Comparison

Typical installation times:
PackageBottle (cold)Bottle (warm)From Source
jq392ms130ms~30s
sqlite625ms159ms~45s
git~800ms~200ms~90s
ffmpeg3481ms688ms~15min
Complex packages like ffmpeg can take 10-30 minutes to build from source depending on your CPU.

​
Dependencies

When building from source, all dependencies are also built from source by default. For example: 
zb install git --build-from-source
This also builds dependencies like openssl, curl, pcre2, etc. from source, significantly increasing build time.

​
Troubleshooting Source Builds

​
Build fails with compiler error

Ensure you have development tools installed: 
# macOS
xcode-select --install

# Linux
which gcc make

​
Missing build dependencies

If a build fails due to missing dependencies: 
error: Failed to build: openssl dependency not found
The dependency should be auto-installed. If not, install it manually: 
zb install openssl
zb install git --build-from-source

​
Build takes too long

Some packages have many dependencies. Check what will be built: 
zb info git
Consider using bottles instead if available: 
zb install git  # Use pre-built bottle

​
Disk space issues

Source builds require temporary disk space for:
  • Source code
  • Intermediate build artifacts
  • Final compiled binaries
Ensure you have several GB of free space for large packages like llvm or gcc.

​
When Bottles Aren’t Available

If no pre-built bottle exists for your platform, zerobrew automatically falls back to building from source: 
zb install some-package
Output: 
==> Installing some-package...
Note: No bottle available, building from source...
No --build-from-source flag is needed in this case.

​
Architecture-Specific Builds

Building from source allows optimization for your CPU:
  • On Apple Silicon (M1/M2), native ARM64 optimizations
  • On Intel, x86_64 optimizations with CPU-specific flags
  • On Linux, distribution-specific optimizations
Bottles are pre-built for common architectures and may not be fully optimized for your specific CPU.

​
Source Code Location

During builds, zerobrew:
  1. Downloads sources to $ZEROBREW_ROOT/cache
  2. Extracts and builds in temporary directories
  3. Installs to $ZEROBREW_ROOT/store/<hash>
  4. Cleans up temporary build artifacts
You can inspect the cache: 
ls $ZEROBREW_ROOT/cache
  • zb install <formula> - Install using bottles (default)
  • zb info <formula> - View package information and dependencies
  • zb gc - Clean up unused store entries and cache files

Build docs developers (and LLMs) love

Get started for freeTalk to us