Overview

stout is designed as a drop-in replacement for Homebrew, which means migrating is straightforward. stout reads Homebrew’s formula format natively, supports the same command syntax, and can even adopt packages already installed by Homebrew without reinstalling them. This guide walks you through every step of the migration, from auditing your current setup to fully cutting over.

Before you start

Make sure you have stout installed. If you have not done that yet, follow the Getting Started guide first.

Take a snapshot of your current Homebrew state so you have a reference:

# Export your installed formulas
brew list --formula > ~/homebrew-formulas.txt

# Export your installed casks
brew list --cask > ~/homebrew-casks.txt

# Export your taps
brew tap > ~/homebrew-taps.txt

# If you use a Brewfile, back it up
cp ~/.Brewfile ~/Brewfile.backup 2>/dev/null

Step 1: Adopt existing Homebrew packages

The fastest migration path is to let stout adopt your existing Homebrew installations in place. This registers Homebrew-installed packages in stout’s database without reinstalling anything:

stout migrate --adopt

This command scans your Homebrew prefix (/usr/local/Cellar on Intel Macs, /opt/homebrew/Cellar on Apple Silicon, /home/linuxbrew/.linuxbrew/Cellar on Linux), reads the installed receipt JSON for each package, and registers them in stout’s internal metadata store.

You will see output like:

==> Scanning Homebrew prefix...
==> Found 147 installed formulas, 23 installed casks
==> Adopting packages...
    adopted [email protected]
    adopted [email protected]
    adopted [email protected]
    ...
==> Adopted 147 formulas and 23 casks (1.2s)

After adoption, verify that stout recognizes your packages:

stout list | head -20

Step 2: Verify compatibility

Run stout’s built-in compatibility check to identify any packages that may need special handling:

stout migrate --check

This reports three categories:

Fully compatible: Packages that work identically under stout.
Needs rebuild: Packages that stout adopted but recommends rebuilding for optimal performance (for example, to take advantage of stout’s optimized build flags).
Manual review: Packages from custom taps or with non-standard install scripts.

For most users, 95%+ of packages fall into the “fully compatible” category.

Step 3: Import your taps

If you use third-party taps, import them into stout:

# Import all existing taps
stout migrate --taps

# Or add taps manually
stout tap add homebrew/cask-fonts
stout tap add some-org/private-tap

stout supports the same tap URL format as Homebrew, so stout tap add user/repo clones from https://github.com/user/homebrew-repo by default.

Step 4: Import your Brewfile

If you maintain a Brewfile (or ~/.Brewfile), stout reads it natively:

stout bundle install --file=Brewfile

stout’s bundle command understands all standard Brewfile directives:

# Brewfile - works with both Homebrew and stout
tap "homebrew/cask-fonts"
tap "some-org/private-tap"

brew "git"
brew "neovim"
brew "ripgrep"
brew "fd"
brew "bat"
brew "eza"
brew "jq"
brew "curl"

cask "firefox"
cask "kitty"
cask "font-jetbrains-mono-nerd-font"

The key difference is speed. Where brew bundle install with this file might take several minutes, stout bundle install resolves all dependencies in parallel and finishes in seconds.

Step 5: Set up the brew alias (optional)

If you want to use brew as the command name (for compatibility with scripts, dotfiles, and muscle memory), stout can create an alias:

stout alias brew

This creates a symlink so that brew install ripgrep invokes stout under the hood. You can always use the stout command directly as well. To remove the alias later:

stout alias --remove brew

Step 6: Uninstall Homebrew (optional)

Once you have confirmed everything works under stout, you can optionally remove Homebrew to reclaim disk space and avoid confusion. stout provides a safe cleanup command:

# Preview what will be removed
stout migrate --cleanup --dry-run

# Actually remove Homebrew artifacts
stout migrate --cleanup

This removes the Homebrew Ruby framework, its Git repository cache, and the brew binary, but leaves all installed packages intact since stout is now managing them.

If you prefer to keep Homebrew around during a transition period, that is fine. stout and Homebrew can coexist on the same system. Just be aware that running brew upgrade and stout upgrade on the same packages can cause conflicts. Pick one manager per package.

Handling edge cases

Packages with post-install scripts

Some Homebrew formulas run post_install blocks that start services or modify system configuration. stout runs these blocks identically, but if you adopted packages without reinstalling, the post-install scripts were not re-executed. For most packages this is fine since the scripts already ran when Homebrew originally installed them.

If you need to re-run post-install logic:

stout reinstall --post-install-only <package>

Custom Homebrew prefixes

If you installed Homebrew to a non-standard location, tell stout where to find it:

stout migrate --adopt --homebrew-prefix /custom/path/to/homebrew

Pinned packages

Homebrew’s brew pin mechanism is supported. stout imports pins automatically during migration:

# Check which packages are pinned
stout list --pinned

# Pin or unpin manually
stout pin node@20
stout unpin node@20

Services

If you use brew services to manage background services (like PostgreSQL or Redis), stout has an equivalent:

# List running services
stout services list

# Start a service
stout services start postgresql@16

# Stop a service
stout services stop postgresql@16

stout’s services are compatible with the same launchd plists (macOS) and systemd unit files (Linux) that Homebrew generates.

Verifying the migration

After completing the migration, run a full verification:

# Check that all packages are healthy
stout doctor

# Run a test upgrade cycle
stout update && stout upgrade --dry-run

The stout doctor command checks for common issues: broken symlinks, missing dependencies, conflicting files, and version mismatches. Address any warnings it reports before considering the migration complete.

Rolling back

If you need to revert to Homebrew for any reason, your backup files from the start of this guide make it easy:

# Reinstall Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Reinstall your packages
xargs brew install < ~/homebrew-formulas.txt
xargs brew install --cask < ~/homebrew-casks.txt

In practice, rollbacks are rare. stout’s Homebrew compatibility is tested against the full homebrew-core formula set on every release.

Migrating from Homebrew to stout