Quick Start¶

Get up and running with Stout in just a few minutes.

First Steps¶

Update the Package Index¶

Before installing packages, update the formula index:

stout update

This downloads the pre-computed package index (about 2MB) - much faster than Homebrew's git-based update.

Search for Packages¶

Find packages with full-text search:

stout search json

Output:

jq                          Lightweight and flexible command-line JSON processor
python-yq                   Command-line YAML and XML processor using jq
gron                        Make JSON greppable
fx                          Terminal JSON viewer
...

Get Package Information¶

View details about a package:

stout info jq

Output:

jq 1.7.1
Lightweight and flexible command-line JSON processor

Homepage: https://jqlang.github.io/jq/
License: MIT

Installed: No

Installing Packages¶

Basic Installation¶

stout install jq

Install Multiple Packages¶

stout install jq yq gron

Install Specific Version¶

stout install python@3.11

Build from Source¶

If a pre-built bottle isn't available:

stout install --build-from-source mypackage

Managing Installed Packages¶

List Installed Packages¶

stout list

Check for Updates¶

stout outdated

Upgrade Packages¶

Upgrade a specific package:

stout upgrade jq

Upgrade all packages:

stout upgrade

Uninstall Packages¶

stout uninstall jq

Remove Unused Dependencies¶

stout autoremove

Exploring Dependencies¶

View Dependencies¶

See what a package depends on:

stout deps python@3.11

View as Tree¶

stout deps --tree python@3.11

Reverse Dependencies¶

See what depends on a package:

stout uses openssl

Why Is This Installed?¶

Trace why a package was installed:

stout why readline

Working with Casks (Applications)¶

Casks are macOS applications (DMG, PKG) and Linux apps (AppImage, Flatpak).

Search for Applications¶

stout cask search firefox

Install an Application¶

stout cask install firefox

List Installed Applications¶

stout cask list

Upgrade Applications¶

stout cask upgrade

System Maintenance¶

Health Check¶

Run diagnostics:

stout doctor

Clean Up¶

Remove old downloads and cache:

stout cleanup

Preview what would be removed:

stout cleanup --dry-run

View Configuration¶

stout config

Helpful Tips¶

Pin Packages¶

Prevent a package from being upgraded:

stout pin node@18

Switch Versions¶

If you have multiple versions installed:

stout switch python 3.11

Rollback¶

Revert to a previous version:

stout rollback python

View History¶

See version history for a package:

stout history python

Common Workflows¶

Developer Setup¶

# Install development tools
stout install git node python@3.11 rust

# Install applications
stout cask install visual-studio-code iterm2

Using Brewfiles¶

If you have an existing Brewfile:

stout bundle install

Create a Brewfile from current installation:

stout bundle dump

Project-Specific Environments¶

Create an isolated prefix:

stout prefix create ~/myproject/.stout
stout --prefix=~/myproject/.stout install node@20 python@3.12

Next Steps¶

Command Reference - Complete command documentation
Configuration - Customize stout settings
Casks Guide - Working with applications

Coexistence with Homebrew¶

Stout's install writes the same Cellar/<formula>/<version>/ layout as Homebrew, links into the same bin/, lib/, and share/ directories under the configured prefix, and emits an INSTALL_RECEIPT.json compatible with the format brew reads. This is intentional — you can run both side-by-side on the same machine and either tool will see the other's packages.

If you adopt stout on a machine that already has Homebrew, the recommended flow is:

# 1. Let stout discover what brew installed
stout import

# 2. Verify everything is tracked
stout list --source brew

# 3. From this point, install via stout for the speed wins
stout install <new-package>

Source Builds¶

Bottles (pre-built binaries) are the default. When a bottle is unavailable for your platform or you explicitly want to build, the source code path is gated behind --build-from-source and supports the same compiler-selection flags Homebrew uses:

stout install --build-from-source --jobs=8 --cc=clang --cxx=clang++ neovim

--HEAD implies --build-from-source and fetches the upstream VCS tip rather than the latest tagged release. Combine with --keep-bottles if you want to retain the downloaded archive after install for debugging.

Resilience Shortcuts¶

If something goes wrong mid-install, these are the quickest recovery moves before reaching for Troubleshooting:

# Refresh and re-verify the index
stout update --force

# Drop cached downloads and bottles
stout cleanup -s

# Re-create symlinks for a package that disappeared from PATH
stout unlink <pkg> && stout link <pkg>

# Detect and repair drift against the Cellar
stout doctor --fix