How to Use brew list to Manage Your Homebrew Packages in 2026

If you manage software on a Mac, Homebrew is almost certainly part of your daily toolkit. Whether you are a developer juggling dozens of command-line utilities or a system administrator auditing what is installed across a fleet of machines, you will eventually need a clear inventory of every package Homebrew has placed on your system. Many users instinctively type brew list installed expecting a tidy readout, only to hit a wall. This guide covers the correct commands, the power-user workflows most articles miss, and the native maintenance tools that keep your Cellar lean — all grounded in the official Homebrew documentation at docs.brew.sh.

The Critical Correction: brew list installed Is a Malformed Command

The single most important thing to understand before going further is that brew list installed is a malformed command. Homebrew does not recognise installed as a valid sub-command or argument to brew list. If you run it, Homebrew will either throw Error: Unknown command: installed or silently ignore the trailing word, depending on your version and shell configuration. The correct command is simply brew list — two words, nothing more. If you arrived here having searched for the three-word variant, you are far from alone, but the fix is immediate: drop installed entirely.

Quick Picks: Core Tools for Managing Installed Packages

How to Choose the Right brew list Flag for the Job

Choosing the correct flag depends on what you are trying to accomplish. If you want a quick, everything-in-one-go inventory, the plain brew list command queries Homebrew’s internal database and outputs every formula and cask currently installed on your Mac. It runs almost instantly, even with hundreds of packages, and it only shows what Homebrew manages — it will not list apps from the Mac App Store, manually downloaded .dmg files, or software installed via other package managers like MacPorts or pip.

However, when you need to separate command-line tools from graphical applications, the filtering flags become essential. According to the official Homebrew manpage (docs.brew.sh/Manpage), brew list --formula restricts the output to formulae only — the command-line tools and libraries installed into Homebrew’s Cellar. Conversely, brew list --cask restricts the output to casks only — the GUI applications managed through Homebrew Cask, such as web browsers, editors, and media players. Knowing which type of package you are auditing matters because formulae and casks are updated, pinned, and uninstalled through different mechanisms.

For version auditing, brew list --versions appends the installed version string to each package name. This is the quickest way to check whether you are running a specific release without querying each package individually. If you deliberately hold a package at an older version, brew list --pinned filters the list to show only those version-pinned packages, which is invaluable when you are ensuring a critical tool does not accidentally upgrade and break a production workflow.

Finally, brew list --unbrewed serves a very specific diagnostic purpose. Per the official Homebrew manpage, it lists files inside the Homebrew prefix that are not in the Cellar or Caskroom — for example, files you or another installer manually placed into /opt/homebrew or /usr/local. This is its precise, current definition and it is not deprecated; it should not be conflated with the broader system health checks performed by brew doctor, which diagnoses configuration and path issues across your entire Homebrew setup.

The Power-User Audit Workflow: brew leaves and brew deps

Most guides stop at brew list and its flags, but the real information gain for a system administrator or developer comes from two commands that Homebrew documents at docs.brew.sh but competitor articles routinely omit: brew leaves and brew deps --installed --tree.

brew leaves — Top-Level Packages Only

When you install a formula, Homebrew automatically installs its dependencies. Over time, brew list becomes cluttered with packages you never explicitly installed — they exist solely to satisfy the requirements of other tools. The brew leaves command solves this by showing only top-level packages: the ones you explicitly requested. This is critical for clean audits because it lets you see exactly what you chose to install, stripping away the noise of transitive dependencies. If you are trying to work out whether you still need a tool, brew leaves is the right starting point.

brew deps --installed --tree — Full Dependency Chains

While brew leaves shows the top of the hierarchy, brew deps --installed --tree renders the full dependency tree for every installed package. This command surfaces hidden dependency chains, making it easy to understand why a seemingly small tool pulls in dozens of supporting libraries. Together, these two commands form the standard power-user audit workflow: run brew leaves to see your explicit installations, then run brew deps --installed --tree to trace the full dependency graph of any package that looks unfamiliar or unnecessary.

Scripting Warning: Do Not Parse brew list in Automation

If you are writing shell scripts, dotfiles management tools, or any form of automation, Homebrew maintainers explicitly advise against parsing brew list output. The reason is that the output format is not guaranteed to be stable across Homebrew versions — a script that parses the default multi-column output today may break when a future update changes the formatting.

For scripting and automation, the safe approach is to use brew list --formula -1. The -1 flag forces one-package-per-line output, producing a machine-parseable format that is far more resilient. This is the documented, maintainers-approved way to enumerate installed formulae in a script, and it should be flagged prominently for any dotfiles or configuration-management use-case.

Migration Tools: Brewfile and mas

Brewfile (brew bundle)

For migrating a setup to a new machine or version-controlling your package list, Homebrew provides the Bundle sub-command. Running brew bundle dump generates a file called a Brewfile — a plain-text manifest of every formula, cask, and App Store application installed on your Mac. To restore that list on a new machine, you simply run brew bundle install from the directory containing the Brewfile, and Homebrew will install everything listed. This is the standard, maintainers-blessed workflow for reproducible Mac setups.

mas (Mac App Store CLI)

For Mac App Store applications, the open-source tool mas (hosted at github.com/mas-cli/mas) bridges the gap between Apple’s App Store and the terminal. Running mas list shows all App Store apps installed for the signed-in Apple ID. If you need to reinstall an app, mas reinstall app-id handles it from the command line — but there is a critical limitation: the app must be already associated with the signed-in Apple ID. You cannot use mas to reinstall purchases from a different account; Apple’s DRM and account-association policies prevent it.

When mas is installed on your system, brew bundle dump automatically includes mas entries in the generated Brewfile. This means a single Brewfile can capture your entire Mac software inventory — Homebrew formulae, Homebrew casks, and Mac App Store applications — in one portable file.

Maintenance: Native Commands Only

Homebrew includes its own maintenance tools, documented at docs.brew.sh, and no third-party “cleaner” applications are needed.

brew autoremove

When you uninstall a formula, Homebrew does not automatically remove the dependencies that were installed alongside it. Over time, this leaves orphaned packages taking up disk space. The brew autoremove command identifies and removes formulae that were installed only as dependencies and are no longer needed by any other package. It is the safe, native way to reclaim space without manually tracing dependency graphs.

brew cleanup

The brew cleanup command deletes old versions of formulae and casks that have been superseded by updates, along with stale cache files downloaded during installations. Running it periodically keeps your Homebrew directory lean. Both brew autoremove and brew cleanup are fully documented native commands — there is no need to install or rely on any third-party tool for routine Homebrew maintenance.

Per-Tool Review: Command-by-Command Breakdown

brew list — The Core Inventory Command

Best for: All users needing a quick, complete inventory of Homebrew-managed software.

What it includes: A plain-text list of every formula and cask currently installed on the system, queried directly from Homebrew’s internal database.

Standout strength: Speed and accuracy — it runs almost instantly and only reports what Homebrew actually manages, avoiding false positives from manually installed software.

Honest caveat: It does not distinguish between packages you explicitly installed and dependencies pulled in automatically; for that, you need brew leaves.

Verdict: The essential first command for any Homebrew user, but only the starting point for a thorough audit.

Where to find it: Pre-installed with Homebrew; documented at docs.brew.sh/Manpage.

brew list --formula and brew list --cask — Filtering Flags

Best for: Users who need to audit command-line tools separately from GUI applications.

What they include: --formula restricts output to formulae (CLI tools and libraries in the Cellar); --cask restricts output to casks (graphical applications in the Caskroom).

Standout strength: Clean separation of two fundamentally different package types, making it easy to spot redundant GUI apps or outdated CLI libraries.

Honest caveat: These flags only filter — they do not provide version numbers or dependency information on their own.

Verdict: Indispensable when you know which package type you are auditing, but combine with --versions or --pinned for deeper insight.

Where to find it: Native Homebrew flags; documented at docs.brew.sh/Manpage.

brew list --versions and brew list --pinned — Version-Aware Flags

Best for: Users checking whether specific versions are installed or confirming that pinned packages remain locked.

What they include: --versions appends the installed version string to each package name; --pinned filters to show only packages deliberately held at a specific version.

Standout strength: Instant visibility into version state without querying each package individually — essential for compliance or compatibility checks.

Honest caveat: Version strings reflect what Homebrew last installed; if a binary has been manually replaced or symlinked elsewhere, the output may not match the actual runtime version.

Verdict: The fastest way to audit versions across an entire installation; pair with --formula or --cask for scoped checks.

Where to find it: Native Homebrew flags; documented at docs.brew.sh/Manpage.

brew bundle (Brewfile) — Migration and Reproducibility

Best for: Developers and system administrators migrating setups or version-controlling their Mac configuration.

What it includes: brew bundle dump generates a Brewfile listing all formulae, casks, and (if mas is installed) Mac App Store applications; brew bundle install restores from that file.

Standout strength: A single portable file captures your entire software inventory, making new-machine provisioning a one-command affair.

Honest caveat: The Brewfile is a snapshot — it does not auto-update when you install new packages, so you must re-run brew bundle dump to keep it current.

Verdict: The gold standard for reproducible Mac setups; essential for anyone who rebuilds or clones machines regularly.

Where to find it: Bundled with Homebrew; documented at docs.brew.sh.

mas — Mac App Store Command-Line Integration

Best for: Users who want terminal control over their Mac App Store purchases alongside Homebrew packages.

What it includes: mas list displays all App Store apps tied to the signed-in Apple ID; mas reinstall app-id reinstalls a specific app by its numeric App Store identifier.

Standout strength: Integrates App Store management into the same terminal workflow as Homebrew, and feeds directly into brew bundle dump for a unified Brewfile.

Honest caveat: mas reinstall only works for apps already associated with the signed-in Apple ID — it cannot reinstall purchases from a different account, which limits its usefulness for multi-account or shared-machine scenarios.

Verdict: A vital bridge between Homebrew and the Mac App Store, provided you stay within a single Apple ID.

Where to find it: Open-source project hosted at github.com/mas-cli/mas; installable via Homebrew.

UK-Specific Notes

Homebrew is a cross-regional package manager; no UK retailers, standards, or regulations apply. The commands, flags, and behaviours described in this guide are identical regardless of your geographic location. There is no localised configuration or regional consideration to factor in.

Frequently Asked Questions

Why does brew list installed not work?

brew list installed is a malformed command. Homebrew does not recognise installed as a valid argument to brew list and will either throw Error: Unknown command: installed or silently ignore the extra word. The correct command is simply brew list, which lists all installed formulae and casks.

How do I list only command-line tools or only GUI apps?

Use brew list --formula to see only formulae (command-line tools and libraries) or brew list --cask to see only casks (graphical applications). Both flags are documented in the official Homebrew manpage at docs.brew.sh/Manpage.

What is the safest way to use brew list output in a shell script?

Homebrew maintainers explicitly advise against parsing the default brew list output in scripts because the format is not guaranteed to be stable across versions. For automation, use brew list --formula -1 — the -1 flag forces one package per line, producing machine-parseable output that is far more resilient to formatting changes.

How do I see which packages I explicitly installed versus dependencies?

Run brew leaves to see only top-level packages — the ones you explicitly requested. Dependencies that were installed solely to satisfy other formulae are excluded. To trace the full dependency chain of any installed package, use brew deps --installed --tree, which renders a visual tree of every dependency relationship.

How do I migrate my Homebrew packages to a new Mac?

Run brew bundle dump to generate a Brewfile — a plain-text manifest of all your installed formulae, casks, and Mac App Store apps (if mas is installed). Copy the Brewfile to your new Mac and run brew bundle install from the same directory. Homebrew will read the file and install everything listed, reproducing your previous setup.

Does mas reinstall work for apps from a different Apple ID?

No. The mas tool (github.com/mas-cli/mas) can only reinstall apps that are already associated with the currently signed-in Apple ID. If an app was purchased or downloaded under a different account, mas reinstall cannot access it. You would need to sign in to the correct Apple ID first, or download the app manually through the App Store interface.

How do I clean up unused and outdated packages without third-party tools?

Homebrew includes two native maintenance commands. brew autoremove removes formulae that were installed only as dependencies and are no longer needed by any remaining package. brew cleanup deletes old, superseded versions and stale download cache files. Both are documented at docs.brew.sh, and no third-party cleaner application is required.

What does brew list --unbrewed actually show?

According to the official Homebrew manpage, brew list --unbrewed lists files inside the Homebrew prefix that are not in the Cellar or Caskroom — typically files manually placed there by the user or another installer. It is not deprecated and should not be confused with brew doctor, which performs broader system health checks.