# How to Use Homebrew on Mac 2026 Published January 1, 2026 · Updated June 25, 2026 How to use Homebrew: the essential brew commands for installing, updating, searching, and removing Mac apps — with copy-paste examples and a maintenance routine. ## Before you start - **Homebrew itself, installed once.** If brew is not on your machine yet, install it first and confirm Terminal finds it with which brew. On Apple Silicon the path is /opt/homebrew/bin/brew; on Intel it is /usr/local/bin/brew. Our new-Mac setup guide walks through the installer and the PATH fix when the shell cannot find it. - **The Xcode command line tools.** Formulae that compile from source need a compiler. The Homebrew installer normally pulls these in; if builds fail with missing headers, run xcode-select --install and let it finish before retrying. Pure cask installs (GUI apps) rarely need this, but having it avoids a whole class of errors. - **An admin account you control.** Installing software writes outside your home folder, so the account needs admin rights. Never work around this with sudo: Homebrew refuses to run as root for good reason, and forcing it breaks file ownership across the install. ## Install & remove - `brew install ` — Install a command-line tool (formula), e.g. brew install git. Homebrew resolves dependencies automatically, so one command often pulls in the libraries the tool needs. - `brew install --cask ` — Install a graphical app (cask), e.g. brew install --cask arc. The app lands in /Applications exactly as if you had downloaded the disk image by hand, minus the dragging. - `brew uninstall ` — Remove a formula. Add --cask for an app. Config files in your home folder usually survive, so reinstalling later picks up where you left off. - `brew list` — List everything you have installed. Run this before upgrades so you know the blast radius, and after a Brewfile restore to confirm nothing was skipped. ## Find software - `brew search ` — Search for formulae and casks by name. Use this whenever a bundle line fails: the token you guessed is often one hyphen off from the real one. - `brew info ` — Show version, dependencies, and the homepage for a package. Read this before installing anything that pulls in five dependencies you did not ask for. ## Keep things current - `brew update` — Refresh the catalog of available packages. Always run this before installing or upgrading; a stale catalog is the top cause of version-not-found errors. - `brew upgrade` — Upgrade everything you have installed to the latest version. Run it when you have time to verify afterward, not ten minutes before a deadline. - `brew outdated` — See which installed packages have updates available. Useful when you want a selective upgrade instead of moving the whole machine at once. ## Maintenance & repair - `brew doctor` — Diagnose common problems with your Homebrew setup. Read each warning literally and fix one item at a time; most are PATH conflicts or leftover files. - `brew cleanup` — Delete old versions and free up disk space. Old versions accumulate fast on machines that upgrade weekly, so this is the easiest gigabytes you will ever reclaim. - `brew bundle dump` — Write a Brewfile of your current setup so you can reproduce it. Commit the file to Git and your next Mac is one command away. ## Your first Homebrew session, step by step 1. **Refresh the catalog.** Start every session by syncing your local copy of available packages. Skipping this is the most common reason an install fails with a version error: your machine is asking for a build the catalog no longer lists. It takes seconds and never changes what is installed, so there is no reason to skip it. ``` brew update ``` 2. **Install one app to learn the shape.** GUI apps are casks, command-line tools are formulae, and the flag matters. Install a launcher like Raycast as a cask and watch where it lands (your /Applications folder, like a manual download). Grant the Accessibility permission it requests on first launch; launchers cannot do their job without it. From here on, every install follows the same pattern. ``` brew install --cask raycast ``` 3. **Install a second app without re-reading docs.** Same command, different token. A terminal such as Ghostty installs the same way, and Homebrew skips anything already present, so repeating commands is harmless. Open it after installing and confirm your shell profile loads; a terminal that cannot find your PATH is a configuration issue, not an install failure. Chain two or three installs in one line while you learn; the pattern holds for every cask in our catalog. ``` brew install --cask ghostty ``` 4. **Check what you have.** List everything installed and inspect anything unfamiliar before you upgrade it. brew info shows the version, dependencies, and homepage, which is worth reading the first time a package pulls in five things you did not ask for. Dependencies install automatically and uninstalling the parent does not always remove them; brew leaves shows what you asked for directly versus what came along for the ride. ``` brew list brew info ghostty ``` 5. **Upgrade everything, then clean up.** One upgrade pass updates all formulae and casks at once. Old versions pile up fast, so finish with cleanup to reclaim disk space. Run this pair weekly and your machine stays current without thought. If one upgrade misbehaves, outdated tells you exactly which packages moved, which narrows the suspect list fast. ``` brew upgrade brew cleanup ``` 6. **Save your setup so it survives.** Dump your current install into a Brewfile and keep that file somewhere safe. Next Mac, next reinstall, you replay one command instead of remembering fifty app names. This is the habit that turns Homebrew from a downloader into a reproducible setup. Commit the file whenever you add something you would miss; a Brewfile you never update is just a souvenir. ``` brew bundle dump --file=~/Brewfile --force ``` ## When a command fails ### "zsh: command not found: brew" in a fresh shell Homebrew installed but your shell never learned where. On Apple Silicon the binary is /opt/homebrew/bin/brew; evaluate the shellenv line once and append it to ~/.zprofile so future shells inherit it. Then quit Terminal completely and reopen it. A new tab is not always enough. ``` eval "$(/opt/homebrew/bin/brew shellenv)" echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile ``` ### Never run brew with sudo If a tutorial tells you sudo brew install, close that tutorial. Homebrew manages its own prefix ownership and running as root corrupts it, producing permission errors that persist after you stop. The fix for a genuine permission problem is to repair ownership of the prefix, not to escalate. When in doubt, brew doctor names the exact directory to look at. ``` brew doctor ``` ### Install fails with "no available formula or cask" Three usual causes, in order: you forgot brew update and the catalog is stale; you used the wrong kind (a GUI app needs --cask, a tool must not have it); or the token is misspelled. Update first, check the kind second, then search for the right name. Cask tokens use lowercase hyphens, exactly as shown in our app pages. ``` brew update brew search ``` ### An upgrade breaks a tool you depend on Do not panic-upgrade everything the morning of a deadline. Upgrade when you have time to verify, keep the previous behavior in mind, and remember cleanup deletes old versions you might have wanted to roll back to. For critical tools, upgrade that one formula alone and test it before running a blanket upgrade. ``` brew upgrade ``` ### A cask app will not open after install macOS Gatekeeper flags freshly installed apps, especially on first launch. Right-click the app in Finder, choose Open, and confirm. This is the operating system doing its job, not a failed install, and it only happens once per app. ### "Your Xcode is outdated" or missing compiler errors Source builds need current command line tools. Run the standalone installer, wait for it to complete, and retry the build. If the error persists after that, the formula itself may be broken upstream; check its homepage or our app page before assuming your machine is at fault. ``` xcode-select --install ``` ### An upgrade moved a tool you needed pinned Some workflows depend on an exact tool version. Pinning a formula excludes it from blanket upgrades while everything else moves forward. Use this sparingly: pinned tools miss security fixes, so revisit pins monthly and unpin once the blocker clears. ``` brew pin brew unpin ``` ### A cask you use daily never shows updates Apps that update themselves (browsers, editors with built-in updaters) are skipped by default upgrades. The greedy flag includes those self-updating casks in the pass. Expect some double updates where both Homebrew and the app updater fire; that overlap is harmless. ``` brew upgrade --cask --greedy ``` ## FAQ ### What is the basic Homebrew workflow? Run brew update to refresh the catalog, brew install (add --cask for apps) to add software, brew upgrade to keep everything current, and brew uninstall to remove it. brew doctor and brew cleanup keep the install healthy. That five-command loop covers nearly everything; the rest of this guide is about doing it in the right order and recovering when a step complains. ### How do I update all my Homebrew apps at once? Run brew update && brew upgrade. The first command refreshes the package list and the second upgrades every installed formula and cask to its latest version. Add the --cask --greedy flags when self-updating apps seem stuck on old versions. ### How do I free up space used by Homebrew? Run brew cleanup to remove outdated versions and cached downloads. Add --prune=all to also clear the entire download cache. On machines that upgrade weekly this routinely frees gigabytes, and it never touches the currently installed versions. ### How do I see everything I have installed? Run brew list to print every installed formula and cask, or brew leaves to see only the top-level packages you installed directly (not dependencies). Pair it with brew info when you want the version and homepage of one package. ### What is the difference between a formula and a cask? A formula is a command-line tool that lives in Homebrew’s prefix and runs in Terminal; a cask is a graphical Mac app that lands in /Applications like a manual download. Install tools with brew install and apps with brew install --cask . Mixing them up is the most common beginner error, and the fix is just adding or removing the flag. When unsure, brew info names the kind before you commit. ### Should I ever use sudo with brew? No, never run brew with sudo. Homebrew owns its install prefix as your user, and escalating to root breaks that ownership and causes permission errors that linger. If an install complains about permissions, run brew doctor and repair the directory it names instead of forcing the command through. Any guide that tells you otherwise is outdated or wrong. ## Related - [How to install apps on Mac](https://bundl.run/guides/how-to-install-apps-mac) - [How to create a Brewfile](https://bundl.run/guides/how-to-create-a-brewfile) - [How to set up a new Mac](https://bundl.run/guides/set-up-a-new-mac) - [Build your Mac setup as one command](https://bundl.run/build) ```json { "@context": "https://schema.org", "@graph": [ { "@type": "Organization", "@id": "https://bundl.run/#organization", "name": "Bundl.run", "url": "https://bundl.run", "logo": { "@type": "ImageObject", "url": "https://bundl.run/og-image.png", "width": 1200, "height": 630 }, "description": "The Ninite for Mac. Install all your essential Mac apps with one terminal command.", "sameAs": [ "https://github.com/abhiofficial/bundl-mac-setup", "https://x.com/bundlrun", "https://www.producthunt.com/products/bundl-run" ], "foundingDate": "2024", "contactPoint": { "@type": "ContactPoint", "contactType": "customer support", "url": "https://bundl.run/faq" } }, { "@type": "WebSite", "@id": "https://bundl.run/#website", "name": "Bundl.run", "url": "https://bundl.run", "description": "The Ninite for Mac. Install all your essential Mac apps with one terminal command.", "publisher": { "@id": "https://bundl.run/#organization" }, "inLanguage": "en-US" }, { "@type": "Person", "@id": "https://bundl.run/authors/alex-chen#person", "name": "Alex Chen", "jobTitle": "Senior Developer Tools Specialist", "url": "https://bundl.run/authors/alex-chen", "worksFor": { "@id": "https://bundl.run/#organization" }, "description": "Alex Chen has been evaluating developer tools and productivity software for over 12 years, with deep expertise in code editors, terminal emulators, and development environments. As a former software engineer at several Bay Area startups, Alex brings hands-on experience with the real-world workflows these tools are meant to enhance. Alex tests each application extensively on both Intel and Apple Silicon Macs, documenting performance metrics, integration capabilities, and workflow efficiency. When not reviewing software, Alex contributes to open-source projects and writes technical tutorials for the developer community.", "knowsAbout": [ "Code Editors & IDEs", "Terminal Emulators", "Version Control Tools", "DevOps & CI/CD", "API Development", "Performance Benchmarking" ], "image": "https://bundl.run/authors/alex-chen.svg" }, { "@type": "BreadcrumbList", "@id": "https://bundl.run/guides/how-to-use-homebrew#breadcrumb", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://bundl.run" }, { "@type": "ListItem", "position": 2, "name": "Guides", "item": "https://bundl.run/guides" }, { "@type": "ListItem", "position": 3, "name": "How to Use Homebrew", "item": "https://bundl.run/guides/how-to-use-homebrew" } ] }, { "@type": "WebPage", "@id": "https://bundl.run/guides/how-to-use-homebrew", "url": "https://bundl.run/guides/how-to-use-homebrew", "name": "How to Use Homebrew on Mac 2026", "description": "How to use Homebrew: the essential brew commands for installing, updating, searching, and removing Mac apps — with copy-paste examples and a maintenance routine.", "isPartOf": { "@id": "https://bundl.run/#website" }, "publisher": { "@id": "https://bundl.run/#organization" }, "inLanguage": "en-US", "datePublished": "2026-01-01", "dateModified": "2026-06-25", "image": "https://bundl.run/og-image.png", "author": { "@id": "https://bundl.run/authors/alex-chen#person" }, "mainEntity": { "@id": "https://bundl.run/guides/how-to-use-homebrew#howto" }, "breadcrumb": { "@id": "https://bundl.run/guides/how-to-use-homebrew#breadcrumb" } }, { "@type": "HowTo", "name": "How to Use Homebrew on Mac", "description": "How to use Homebrew: the essential brew commands for installing, updating, searching, and removing Mac apps — with copy-paste examples and a maintenance routine.", "tool": [ { "@type": "HowToTool", "name": "Homebrew" }, { "@type": "HowToTool", "name": "Terminal" } ], "step": [ { "@type": "HowToStep", "position": 1, "name": "Refresh the catalog", "text": "Start every session by syncing your local copy of available packages. Skipping this is the most common reason an install fails with a version error: your machine is asking for a build the catalog no longer lists. It takes seconds and never changes what is installed, so there is no reason to skip it.", "url": "https://bundl.run/guides/how-to-use-homebrew#step-1" }, { "@type": "HowToStep", "position": 2, "name": "Install one app to learn the shape", "text": "GUI apps are casks, command-line tools are formulae, and the flag matters. Install a launcher like Raycast as a cask and watch where it lands (your /Applications folder, like a manual download). Grant the Accessibility permission it requests on first launch; launchers cannot do their job without it. From here on, every install follows the same pattern.", "url": "https://bundl.run/guides/how-to-use-homebrew#step-2" }, { "@type": "HowToStep", "position": 3, "name": "Install a second app without re-reading docs", "text": "Same command, different token. A terminal such as Ghostty installs the same way, and Homebrew skips anything already present, so repeating commands is harmless. Open it after installing and confirm your shell profile loads; a terminal that cannot find your PATH is a configuration issue, not an install failure. Chain two or three installs in one line while you learn; the pattern holds for every cask in our catalog.", "url": "https://bundl.run/guides/how-to-use-homebrew#step-3" }, { "@type": "HowToStep", "position": 4, "name": "Check what you have", "text": "List everything installed and inspect anything unfamiliar before you upgrade it. brew info shows the version, dependencies, and homepage, which is worth reading the first time a package pulls in five things you did not ask for. Dependencies install automatically and uninstalling the parent does not always remove them; brew leaves shows what you asked for directly versus what came along for the ride.", "url": "https://bundl.run/guides/how-to-use-homebrew#step-4" }, { "@type": "HowToStep", "position": 5, "name": "Upgrade everything, then clean up", "text": "One upgrade pass updates all formulae and casks at once. Old versions pile up fast, so finish with cleanup to reclaim disk space. Run this pair weekly and your machine stays current without thought. If one upgrade misbehaves, outdated tells you exactly which packages moved, which narrows the suspect list fast.", "url": "https://bundl.run/guides/how-to-use-homebrew#step-5" }, { "@type": "HowToStep", "position": 6, "name": "Save your setup so it survives", "text": "Dump your current install into a Brewfile and keep that file somewhere safe. Next Mac, next reinstall, you replay one command instead of remembering fifty app names. This is the habit that turns Homebrew from a downloader into a reproducible setup. Commit the file whenever you add something you would miss; a Brewfile you never update is just a souvenir.", "url": "https://bundl.run/guides/how-to-use-homebrew#step-6" } ], "@id": "https://bundl.run/guides/how-to-use-homebrew#howto", "author": { "@id": "https://bundl.run/authors/alex-chen#person" } }, { "@type": "FAQPage", "@id": "https://bundl.run/guides/how-to-use-homebrew#faq", "mainEntity": [ { "@type": "Question", "name": "What is the basic Homebrew workflow?", "acceptedAnswer": { "@type": "Answer", "text": "Run brew update to refresh the catalog, brew install (add --cask for apps) to add software, brew upgrade to keep everything current, and brew uninstall to remove it. brew doctor and brew cleanup keep the install healthy. That five-command loop covers nearly everything; the rest of this guide is about doing it in the right order and recovering when a step complains." } }, { "@type": "Question", "name": "How do I update all my Homebrew apps at once?", "acceptedAnswer": { "@type": "Answer", "text": "Run brew update && brew upgrade. The first command refreshes the package list and the second upgrades every installed formula and cask to its latest version. Add the --cask --greedy flags when self-updating apps seem stuck on old versions." } }, { "@type": "Question", "name": "How do I free up space used by Homebrew?", "acceptedAnswer": { "@type": "Answer", "text": "Run brew cleanup to remove outdated versions and cached downloads. Add --prune=all to also clear the entire download cache. On machines that upgrade weekly this routinely frees gigabytes, and it never touches the currently installed versions." } }, { "@type": "Question", "name": "How do I see everything I have installed?", "acceptedAnswer": { "@type": "Answer", "text": "Run brew list to print every installed formula and cask, or brew leaves to see only the top-level packages you installed directly (not dependencies). Pair it with brew info when you want the version and homepage of one package." } }, { "@type": "Question", "name": "What is the difference between a formula and a cask?", "acceptedAnswer": { "@type": "Answer", "text": "A formula is a command-line tool that lives in Homebrew’s prefix and runs in Terminal; a cask is a graphical Mac app that lands in /Applications like a manual download. Install tools with brew install and apps with brew install --cask . Mixing them up is the most common beginner error, and the fix is just adding or removing the flag. When unsure, brew info names the kind before you commit." } }, { "@type": "Question", "name": "Should I ever use sudo with brew?", "acceptedAnswer": { "@type": "Answer", "text": "No, never run brew with sudo. Homebrew owns its install prefix as your user, and escalating to root breaks that ownership and causes permission errors that linger. If an install complains about permissions, run brew doctor and repair the directory it names instead of forcing the command through. Any guide that tells you otherwise is outdated or wrong." } } ], "isPartOf": { "@id": "https://bundl.run/guides/how-to-use-homebrew" } } ] } ```