FAQ¶

Frequently asked questions about Stout.

General¶

What is Stout?¶

Stout is a fast, Rust-based package manager that's compatible with Homebrew. It provides the same commands and uses the same package ecosystem, but runs 10-100x faster.

Why is Stout faster than Homebrew?¶

Several design choices make Stout faster:

No Ruby - Native Rust binary starts in 5ms vs 500ms
No Git - Downloads 2MB index vs 700MB+ Git operations
Pre-computed metadata - SQLite with FTS5, not runtime Ruby evaluation
Parallel downloads - Async Tokio runtime for concurrent operations
Smart caching - Aggressive caching with hash-based invalidation

Can I use Stout alongside Homebrew?¶

Yes. Stout uses the same Cellar structure and creates compatible receipt files. Packages installed by either tool are visible to both.

Does Stout support all Homebrew packages?¶

Stout supports packages that provide pre-built bottles. Building from source is supported but less tested than Homebrew's build system.

Installation¶

How do I install Stout?¶

The quickest method:

curl -fsSL https://raw.githubusercontent.com/neul-labs/stout/main/install.sh | bash

See Installation for more options.

What platforms are supported?¶

macOS 12+ (Intel and Apple Silicon)
Linux (glibc 2.17+, x86_64 and arm64)

How do I update Stout?¶

# If installed via the install script
curl -fsSL https://raw.githubusercontent.com/neul-labs/stout/main/install.sh | bash

# If installed via package manager
npm update -g stout-pkg  # or pip, gem, etc.

How do I uninstall Stout?¶

rm ~/.local/bin/stout
rm -rf ~/.stout

Usage¶

How do I search for packages?¶

stout search <query>

Stout uses full-text search, so partial matches work well.

How do I install a specific version?¶

stout install python@3.11

How do I see what's installed?¶

stout list

How do I update all packages?¶

stout upgrade

How do I prevent a package from updating?¶

stout pin <package>

Where are packages installed?¶

Same location as Homebrew:

macOS: /opt/homebrew/Cellar
Linux: /home/linuxbrew/.linuxbrew/Cellar

Compatibility¶

Can I use my existing Brewfile?¶

Yes:

stout bundle install

Are Homebrew taps supported?¶

Tap support is available:

stout tap user/repo

Do post-install scripts run?¶

No. Stout doesn't execute Ruby scripts. If a package requires post-install setup, you'll need to run it manually. This is a security feature.

What about caveats?¶

Caveats (post-install instructions) are displayed after installation, same as Homebrew.

Casks¶

What are casks?¶

Casks are macOS applications (like Firefox, VS Code) and Linux desktop apps.

How do I install a cask?¶

stout cask install firefox

Where are applications installed?¶

macOS: /Applications or ~/Applications
Linux: ~/.local/share/appimages

Security¶

How does Stout verify packages?¶

Two layers of verification:

Index: Ed25519 cryptographic signatures
Packages: SHA256 checksums

Is the index signed?¶

Yes. The package index is signed with Ed25519. Stout refuses to use an index with an invalid signature.

Can I use a private index?¶

Yes. See Enterprise for details on hosting your own package index.

How do I check for vulnerabilities?¶

stout audit

Troubleshooting¶

"Command not found: stout"¶

Add the installation directory to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Add this to your shell's rc file (~/.bashrc, ~/.zshrc, etc.)

"Signature verification failed"¶

The package index signature is invalid. This could mean:

Network corruption
Index has been tampered with
Stale cache

Try:

rm -rf ~/.stout/cache
stout update --force

"Package not found"¶

Update your package index:

stout update

If still not found, the package may not exist or may be in a tap:

stout search <partial-name>

Installation fails with permission error¶

Check that you own the Cellar directory:

sudo chown -R $(whoami) /opt/homebrew

Or use a custom prefix:

stout prefix create ~/.local/stout
stout --prefix=~/.local/stout install <package>

"Too many open files"¶

Increase your ulimit:

ulimit -n 10240

Make permanent by adding to shell rc file.

Configuration¶

Where is the config file?¶

~/.stout/config.toml

How do I change the number of parallel downloads?¶

[install]
parallel_downloads = 8

How do I use a mirror?¶

stout --mirror=http://mirror.example.com install jq

Or in config:

[mirror]
url = "http://mirror.example.com"

Development¶

How do I build Stout from source?¶

git clone https://github.com/neul-labs/stout.git
cd stout
cargo build --release

How do I contribute?¶

See the Contributing Guide.

Where do I report bugs?¶

Open an issue at github.com/neul-labs/stout/issues.

Architecture & Internals¶

What's the on-disk size of the index?¶

The compressed SQLite formula index is roughly 3 MB and includes the FTS5 search vocabulary. Compare this to Homebrew's full git checkout, which is 700 MB+ and grows continuously. The cask index is similar in shape; the optional CVE database used by stout audit adds another small SQLite file.

How does stout build the index?¶

scripts/sync.py walks the official Homebrew API, normalises each formula into a JSON document, and writes it into the SQLite schema defined in the stout-index crate. Sibling scripts handle casks (sync_casks.py), Linux apps (sync_linux_apps.py), and CVE data (sync_vulns.py). The sync output is published to the neul-labs/stout-index repository, which is what every client downloads via stout update.

What Rust version is required?¶

The workspace Cargo.toml pins rust-version = "1.85". Earlier versions will fail to compile from source.

Which crates make up stout?¶

stout (binary)
├── stout-index    SQLite + FTS5 index, signature verification
├── stout-resolve  Dependency graph and version selection
├── stout-fetch    HTTPS downloads, checksum verification
├── stout-install  Bottle extraction, relocation, symlinks, receipts
├── stout-state    Local state DB, pins, history, prefix tracking
├── stout-cask     Cask format handling (DMG/PKG/AppImage/Flatpak)
├── stout-bundle   Brewfile, snapshots, lockfiles
├── stout-audit    CVE scanning
└── stout-mirror   Offline mirror create/serve/verify

Each crate is independently versioned alongside the top-level binary in the workspace.

Distribution¶

Where can I get stout?¶

Stout is published to several distribution channels simultaneously:

GitHub Releases (raw binaries + checksums)
npm: stout-pkg
PyPI: stout-pkg
crates.io: stout
Homebrew tap: neul-labs/tap/stout
Arch User Repository: stout-bin
Nix flake (in packaging/nix/)
.deb and .rpm packages on the releases page

The release workflow builds each of these from the same Rust binary, so all channels ship the same artifact.

Why npm / pip wrappers for a Rust binary?¶

The npm and pip packages are thin shims that download the appropriate pre-built binary on postinstall, then expose it on the user's PATH. This lets stout participate in workflows that already standardise on package.json or requirements.txt for tool installation without forcing users to learn yet another installer.