1<!DOCTYPE html> 2<html lang="en"> 3 <head> 4 <meta http-equiv="Content-Security-Policy" 5 content="default-src 'none'; 6 connect-src https://D9HG3G8GS4-dsn.algolia.net https://D9HG3G8GS4-1.algolianet.com https://D9HG3G8GS4-2.algolianet.com https://D9HG3G8GS4-3.algolianet.com; 7 font-src data: https://fonts.gstatic.com; 8 img-src 'self' https://avatars2.githubusercontent.com https://avatars.githubusercontent.com https://brew.sh https://github.com; 9 object-src 'none'; 10 form-action 'self'; 11 12 script-src 'self' 'unsafe-inline' https://cdnjs.cloudflare.com ; 13 style-src 'self' 'unsafe-inline' https://brew.sh https://cdnjs.cloudflare.com; 14 15 "> 16 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 17 <title>Homebrew Documentation: Installation</title> 18 <!-- Begin Jekyll SEO tag v2.9.0 --> 19<meta name="generator" content="Jekyll v4.4.1"> 20<meta property="og:title" content="Installation"> 21<meta property="og:locale" content="en_US"> 22<meta name="description" content="Documentation for the package manager for everywhere."> 23<meta name="twitter:description" property="og:description" content="Documentation for the package manager for everywhere."> 24<link rel="canonical" href="https://docs.brew.sh/Installation"> 25<meta property="og:url" content="https://docs.brew.sh/Installation"> 26<meta property="og:site_name" content="Homebrew Documentation"> 27<meta property="og:image" content="https://brew.sh/assets/img/homebrew-256x256.png"> 28<meta property="og:type" content="website"> 29<meta name="twitter:card" content="summary_large_image"> 30<meta name="twitter:image" content="https://brew.sh/assets/img/homebrew-256x256.png"> 31<meta name="twitter:title" content="Installation"> 32<meta name="twitter:site" content="@MacHomebrew"> 33<meta property="article:publisher" content="https://www.facebook.com/machomebrew/">
34<script type="application/ld+json"> 35{"@context":"https://schema.org","@type":"WebPage","description":"Documentation for the package manager for everywhere.","headline":"Installation","image":"https://brew.sh/assets/img/homebrew-256x256.png","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"https://brew.sh/assets/img/homebrew.svg"}},"url":"https://docs.brew.sh/Installation"}</script>
35 36<!-- End Jekyll SEO tag --> 37 38 <meta name="viewport" content="width=device-width"> 39 <link rel="icon" href="https://brew.sh/assets/img/favicon.ico" sizes="48x48"> 40 <link rel="icon" href="https://brew.sh/assets/img/homebrew.svg" sizes="any" type="image/svg+xml"> 41 <link rel="apple-touch-icon" href="https://brew.sh/assets/img/apple-touch-icon.png"> 42 <link rel="stylesheet" href="https://brew.sh/assets/css/style.css" type="text/css" media="screen"> 43 <link rel="preconnect" href="https://D9HG3G8GS4-dsn.algolia.net" crossorigin> 44 <link rel="preload" href="https://cdnjs.cloudflare.com/ajax/libs/docsearch-css/3.9.0/style.min.css" integrity="sha512-sIgq4M6w/5zPkFzkEpaTuKtZnko/4fsTWj/4XcsVLfpj5q68YkybfOxxLidjo5yZ16dsidABSz4RaapCvzbntQ==" crossorigin="anonymous" referrerpolicy="no-referrer" as="style" media="screen" onload="this.onload=null;this.rel='stylesheet'"> 45 </head> 46 <body> 47 <div id="wrap"> 48 <header id="header"> 49 <div id="brand"> 50 <img alt="Homebrew Documentation logo" src="https://brew.sh/assets/img/homebrew.svg" width="128" height="128"> 51 <h1><a href="/">Homebrew Documentation</a></h1> 52 </div> 53 <div id="header-controls"> 54 <div id="search-container"></div> 55 56 </div> 57 </header> 58 59 <main> 60 <div id="default"> 61 <h1 id="installation">Installation</h1> 62 63<p>Instructions for a supported install of Homebrew are on the <a href="https://brew.sh/">homepage</a>.</p> 64 65<p>The script installs Homebrew to its default prefix (<code class="language-plaintext highlighter-rouge">/opt/homebrew</code> for Apple Silicon, <code class="language-plaintext highlighter-rouge">/usr/local</code> for macOS Intel and <code class="language-plaintext highlighter-rouge">/home/linuxbrew/.linuxbrew</code> for Linux) so that <a href="/FAQ#why-does-homebrew-say-sudo-is-bad">you donât need <em>sudo</em> after Homebrewâs initial installation</a> when you install formulae. 66Some casks and system services still require elevated privileges. 67Custom prefixes can also use bottles (binary packages); see their <a href="/Support-Tiers#custom-prefixes">Tier 1 requirements and stability caveat</a>. 68It is a careful script; it can be run even if you have stuff installed in the preferred prefix already. 69It tells you exactly what it will do before it does it too. 70You have to confirm everything it will do before it starts.</p> 71 72<p>The macOS <code class="language-plaintext highlighter-rouge">.pkg</code> installer supports only Apple Silicon and also installs Homebrew to its default prefix (<code class="language-plaintext highlighter-rouge">/opt/homebrew</code>) for the same reasons as above. 73It is available on <a href="https://github.com/Homebrew/brew/releases/latest">Homebrew/brewâs latest GitHub release</a>. 74To specify an alternate install user, such as when the package is installed at the login window before a user has logged in, create <code class="language-plaintext highlighter-rouge">/var/tmp/.homebrew_pkg_user.plist</code> with a <code class="language-plaintext highlighter-rouge">HOMEBREW_PKG_USER</code> value before installation:</p> 75 76<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">sudo </span>defaults write /var/tmp/.homebrew_pkg_user HOMEBREW_PKG_USER penny 77<span class="nb">sudo chown </span>root:wheel /var/tmp/.homebrew_pkg_user.plist 78<span class="nb">sudo chmod </span>600 /var/tmp/.homebrew_pkg_user.plist 79<span class="nb">sudo chmod</span> <span class="nt">-N</span> /var/tmp/.homebrew_pkg_user.plist 80</code></pre></div></div> 81 82<p>The file must be a regular non-symlink file owned by <code class="language-plaintext highlighter-rouge">root</code>, have mode <code class="language-plaintext highlighter-rouge">0600</code> and have no access control list. 83The installer ignores an override that does not meet these requirements and falls back to the active console user. 84The selected user must exist before installation and must not be <code class="language-plaintext highlighter-rouge">root</code>. 85When developer tools provide Git, the installer runs repository maintenance as this user.
86See <a href="/Homebrew-for-Mac-Admins">Homebrew for Mac Admins</a> for deployment through MDM, non-admin accounts and central configuration.</p> 87 88<p>Homebrew provides no security guarantees for installations where users with write permissions to the Homebrew prefix are considered untrusted. 89This also applies to installations and upgrades performed with the macOS <code class="language-plaintext highlighter-rouge">.pkg</code> installer, including through MDM.</p> 90 91<h2 id="macos-requirements">macOS requirements</h2> 92 93<ul> 94 <li>An Apple Silicon CPU; using a 64-bit Intel CPU is a <a href="/Support-Tiers#tier-3">Tier 3</a> configuration <sup><a href="#1">1</a></sup></li> 95 <li>macOS Sequoia (15) (or higher) installed on officially supported hardware<sup><a href="#2">2</a></sup></li> 96 <li>When building formulae from source, Command Line Tools (CLT) for Xcode (from <code class="language-plaintext highlighter-rouge">xcode-select --install</code> or 97<a href="https://developer.apple.com/download/all/">https://developer.apple.com/download/all/</a>) or 98<a href="https://itunes.apple.com/us/app/xcode/id497799835">Xcode</a> <sup><a href="#3">3</a></sup></li> 99 <li>The Bourne-again shell for installation (i.e. <code class="language-plaintext highlighter-rouge">bash</code>) <sup><a href="#4">4</a></sup></li> 100</ul> 101 102<h2 id="advanced-configuration">Advanced configuration</h2> 103 104<p>The Homebrew installer offers various advanced configuration settings. <strong>Most users can skip this section and instead follow the instructions on the <a href="https://brew.sh/">homepage</a>!</strong></p> 105 106<h3 id="running-without-sudo">Running without sudo</h3> 107 108<p>Homebrew can be installed for a non-admin account. 109The shell installer needs a writable prefix; arrange initial provisioning if needed, or use <code class="language-plaintext highlighter-rouge">--path</code> to select a <a href="/Support-Tiers#custom-prefixes">compatible custom prefix</a>. 110The macOS <code class="language-plaintext highlighter-rouge">.pkg</code> installer can provision the default prefix for the account selected by <code class="language-plaintext highlighter-rouge">HOMEBREW_PKG_USER</code> above. 111After provisioning, run routine Homebrew commands as that account; formula installation and updates do not require sudo.</p> 112 113<p>On macOS, if the account is not an administrator and its primary group is <code class="language-plaintext highlighter-rouge">staff</code>, installation and reinstallation remove group and other write permissions from the prefix and cache. 114Homebrew also restricts its umask for this account, including subprocesses, while preserving stricter existing umasks. 115Permissions for administrator accounts and accounts with custom primary groups are unchanged.</p> 116 117<p>To disable Homebrewâs sudo calls explicitly:</p> 118 119<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">export </span><span class="nv">HOMEBREW_NO_SUDO</span><span class="o">=</span>1 120</code></pre></div></div> 121 122<p>When unset, Homebrew disables sudo only when it is missing, reports a recognised inability to elevate privileges or a non-interactive check explicitly denies access. 123Password requirements and inconclusive failures preserve normal behaviour. 124Optional filesystem operations try without sudo before retrying with it. 125When sudo is disabled, casks requiring it for installers, keyboard layouts or install steps are rejected before installation. 126Homebrew does not substitute manual <code class="language-plaintext highlighter-rouge">.pkg</code> extraction for installation because it would skip installer scripts and package receipts. 127For compatible app casks, use a writable destination such as <code class="language-plaintext highlighter-rouge">brew install --cask --appdir="$HOME/Applications" <cask></code>. 128This setting does not control commands run internally by third-party installers.</p> 129 130<h3 id="running-as-the-homebrew-owner">Running as the Homebrew owner</h3> 131 132<p>A dedicated account can manage Homebrew while other accounts read and execute its installed software. 133Give the owner a writable home directory and write access to the Homebrew directories and any shared app destination. 134Non-admin installations use the accountâs primary group, including a custom group; membership of <code class="language-plaintext highlighter-rouge">admin</code> or <code class="language-plaintext highlighter-rouge">staff</code> is not required. 135When already running as the owner, invoke <code class="language-plaintext highlighter-rouge">brew</code> normally. 136To select the prefix owner from another account or a deployment process running as root on macOS or Linux, use:</p> 137 138<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>brew as-brew-user <span class="nb">install </span>wget 139</code></pre></div></div> 140 141<p>The command uses the ownerâs home and a clean environment, switching accounts through sudo when necessary. 142When sudo is disabled or unavailable, an already-root process switches through macOS <code class="language-plaintext highlighter-rouge">login</code> or Linux <code class="language-plaintext highlighter-rouge">runuser</code> instead. 143These commands use the selected accountâs primary and supplementary groups. 144Without permission to switch accounts, log in as the owner instead. 145No console login is needed for <code class="language-plaintext highlighter-rouge">as-brew-user</code>. 146A root-owned prefix is rejected; directory ownership is not changed. 147User services, caches and personal configuration belong to the managing account. 148Run <code class="language-plaintext highlighter-rouge">brew doctor</code> as that account and check group permissions and access control lists before sharing the installation.</p> 149 150<h3 id="running-as-the-console-user">Running as the console user</h3> 151 152<p>On macOS, MDM, Munki and Jamf workflows can run Homebrew as the active logged-in console user:</p> 153 154<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>brew as-console-user <span class="nb">install </span>wget 155</code></pre></div></div> 156 157<p>The command uses that userâs home and a clean environment. 158An already-root process can switch users even when sudo is disabled or unavailable, using the same fallback as <code class="language-plaintext highlighter-rouge">as-brew-user</code>. 159Other accounts need sudo access to switch users. 160It fails if no supported console user is logged in. 161Use <code class="language-plaintext highlighter-rouge">as-brew-user</code> above when a dedicated account owns Homebrew.</p> 162 163<h3 id="git-remote-mirroring">Git remote mirroring</h3> 164 165<p>If you have issues connecting to GitHub.com, you can use Git mirrors for Homebrewâs installation and <code class="language-plaintext highlighter-rouge">brew update</code> by setting <code class="language-plaintext highlighter-rouge">HOMEBREW_BREW_GIT_REMOTE</code>
165 and/or <code class="language-plaintext highlighter-rouge">HOMEBREW_CORE_GIT_REMOTE</code> in your shell environment with this script:</p> 166 167<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">export </span><span class="nv">HOMEBREW_BREW_GIT_REMOTE</span><span class="o">=</span><span class="s2">"..."</span> <span class="c"># put your Git mirror of Homebrew/brew here</span> 168<span class="nb">export </span><span class="nv">HOMEBREW_CORE_GIT_REMOTE</span><span class="o">=</span><span class="s2">"..."</span> <span class="c"># put your Git mirror of Homebrew/homebrew-core here</span> 169/bin/bash <span class="nt">-c</span> <span class="s2">"</span><span class="si">$(</span>curl <span class="nt">-fsSL</span> https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh<span class="si">)</span><span class="s2">"</span> 170</code></pre></div></div> 171 172<p>The default Git remote will be used if the corresponding environment variable is unset and works best for most users.</p> 173 174<p><strong>Note:</strong> if you set these variables you are granting these repositories the same level of trust you currently grant to Homebrew itself. You should be extremely confident that these repositories will not be compromised.</p> 175 176<h3 id="default-tap-cloning">Default tap cloning</h3> 177 178<p>You can instruct Homebrew to return to pre-4.0.0 behaviour by cloning the Homebrew/homebrew-core tap during installation by setting the <code class="language-plaintext highlighter-rouge">HOMEBREW_NO_INSTALL_FROM_API</code> environment variable with the following:</p> 179 180<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">export </span><span class="nv">HOMEBREW_NO_INSTALL_FROM_API</span><span class="o">=</span>1 181/bin/bash <span class="nt">-c</span> <span class="s2">"</span><span class="si">$(</span>curl <span class="nt">-fsSL</span> https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh<span class="si">)</span><span class="s2">"</span> 182</code></pre></div></div> 183 184<p>This will make Homebrew install formulae and casks from the <code class="language-plaintext highlighter-rouge">homebrew/core</code> and <code class="language-plaintext highlighter-rouge">homebrew/cask</code> taps using local checkouts of these repositories instead of Homebrewâs API. Unless you are a Homebrew maintainer or contributor, you should probably not globally enable this setting. It can easily be enabled later after installation should it be necessary.</p> 185 186<h3 id="unattended-installation">Unattended installation</h3> 187 188<p>If you want a non-interactive run of the Homebrew installer that doesnât prompt for passwords (e.g. in automation scripts), prepend <a href="https://github.com/Homebrew/install/#install-homebrew-on-macos-or-linux"><code class="language-plaintext highlighter-rouge">NONINTERACTIVE=1</code></a> to the installation command.</p> 189 190<h2 id="alternative-installs">Alternative installs</h2> 191 192<h3 id="linux-or-windows-10-subsystem-for-linux">Linux or Windows 10 Subsystem for Linux</h3> 193 194<p>Check out the documentation for installing <a href="/Homebrew-on-Linux">Homebrew on Linux</a>.</p> 195 196<h2 id="post-installation-steps">Post-installation steps</h2> 197 198<p>When you install Homebrew, it prints some directions for updating your shellâs config. 199If you donât follow those directions, Homebrew will not work.</p> 200 201<p>You need to update your shellâs config file (which file exactly depends on your shell, for example <code class="language-plaintext highlighter-rouge">~/.bashrc</code> or <code class="language-plaintext highlighter-rouge">~/.zshrc</code>) to include this:</p> 202 203<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">eval</span> <span class="s2">"</span><span class="si">$(</span><Homebrew prefix path>/bin/brew shellenv<span class="si">)</span><span class="s2">"</span> 204</code></pre></div></div> 205 206<p>Replace <code class="language-plaintext highlighter-rouge"><Homebrew prefix path></code> with the directory where Homebrew is installed on your system. 207You can find Homebrewâs default install location in <a href="/FAQ#why-should-i-install-homebrew-in-the-default-location">this FAQ entry</a>.</p> 208 209<p>For more insight, re-run the installer or inspect the <a href="https://github.com/Homebrew/install/blob/700c9a145d37a3f0f3bd3b7c208d7adab31bd278/install.sh#L1104-L1120">installerâs source</a> to see how the installer constructs the path it recommends.</p> 210 211<p>See <a href="/Tips-and-Tricks#load-homebrew-from-the-same-dotfiles-on-different-operating-systems">this tip in Tips and Tricks</a> for another way to handle this across multiple operating systems.</p> 212 213<h2 id="uninstallation">Uninstallation</h2> 214 215<p>Uninstallation is documented in the <a href="/FAQ#how-do-i-uninstall-homebrew">FAQ</a>.</p> 216 217<p><a data-proofer-ignore="" name="1"><sup>1</sup></a> For 32-bit or PPC support see <a href="https://www.macports.org">MacPorts</a> or <a href="https://github.com/mistydemeo/tigerbrew">Tigerbrew</a>.</p> 218 219<p><a data-proofer-ignore="" name="2"><sup>2</sup></a> On Apple Silicon, macOS 15 (Sequoia) through 27 (Golden Gate) is best and supported; macOS 11 (Big Sur) â 14 (Sonoma) are unsupported but may work. 220All Intel Mac configurations that can run Homebrew, including those using OpenCore Legacy Patcher, are <a href="/Support-Tiers#tier-3">Tier 3</a>. 221macOS 10.15 (Catalina) and older will not run Homebrew at all.</p> 222 223<p><a data-proofer-ignore="" name="3"><sup>3</sup></a> Xcode or the CLT is required to build formulae from source. On Apple Silicon, casks and bottles can be installed without developer tools. Intel macOS also requires developer tools for bottle installation. Downloading Xcode may require an Apple Developer account on older versions of Mac OS X. Sign up for free at <a href="https://developer.apple.com/account/">Appleâs website</a>.</p> 224 225<p><a data-proofer-ignore="" name="4"><sup>4</sup></a> The one-liner installation method found on <a href="https://brew.sh/">brew.sh</a> uses the Bourne-again shell at <code class="language-plaintext highlighter-rouge">/bin/bash</code>. Notably, <code class="language-plaintext highlighter-rouge">zsh</code>, <code class="language-plaintext highlighter-rouge">fish</code>, <code class="language-plaintext highlighter-rouge">tcsh</code> and <code class="language-plaintext highlighter-rouge">csh</code> will not work.</p> 226 227</div> 228 229 </main> 230 </div> 231 232 <aside> 233 <a href="https://github.com/Homebrew/brew"> 234 <img id="forkme" src="https://brew.sh/assets/img/forkme_right_gray_6d6d6d.svg" alt="Fork me on GitHub"> 235 </a> 236 </aside> 237
237<script> 238 function loadLanguage(lang) { 239 if (lang === null) { 240 return; 241 } else if (lang === 'en') { 242 window.location.assign('/'); 243 } else { 244 window.location.assign('/' + lang); 245 } 246 } 247 248 function loadAnchors() { 249 anchors.options = { 250 placement: 'left', 251 visible: 'hover', 252 }; 253 anchors.add('#page > h2, #page > h3, #page > h4, #page > h5, #page > h6'); 254 }; 255 256 function loadSearch(lang, site) { 257 docsearch(Object.assign( 258 { searchParameters: { facetFilters: ['site:' + site] } }, 259 { initialQuery: new URLSearchParams(window.location.search).get('search') }, 260 { placeholder: "Search Documentation" }, 261 {"apiKey":"e3369d62b2366b374c54b2c5a2835a00","indexName":"brew_all","appId":"D9HG3G8GS4","container":"#search-container"} 262 )); 263 }; 264 265 async function setupCopyables() { 266 if (navigator.clipboard) { 267 for (const element of document.getElementsByClassName('copyable')) { 268 let text = element.innerText.trim(); 269 if (text.startsWith('$')) { 270 text = text.slice(1).trimStart(); 271 } 272 273 274 const button = document.createElement('button'); 275 button.type = 'button'; 276 button.textContent = 'â§'; 277 button.setAttribute('aria-label', 'Copy to clipboard'); 278 button.onclick = () => { 279 navigator.clipboard.writeText(text); 280 button.textContent = 'â'; 281 setTimeout(() => button.textContent = 'â§', 1000); 282 } 283 element.appendChild(button); 284 } 285 } 286 } 287 288 window.addEventListener("DOMContentLoaded", function() { 289 setupCopyables(); 290 }); 291 </script>
291 292
292<script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/5.0.0/anchor.min.js" 293 integrity="sha512-byAcNWVEzFfu+tZItctr+WIMUJvpzT2kokkqcBq+VsrM3OrC5Aj9E2gh+hHpU0XNA3wDmX4sDbV5/nkhvTrj4w==" 294 crossorigin="anonymous" 295 referrerpolicy="no-referrer" 296 onload="loadAnchors()" 297 async></script>
297 298
298<script src="https://cdnjs.cloudflare.com/ajax/libs/docsearch-js/3.9.0/umd/index.min.js" 299 integrity="sha512-GQvKUarIhGPpbful5R03aNwrhDKd/b+KdasOD9Uq0SFTZHJV14rly+Uss2pKazgeZz+G3JQ0wk1ximS6crma/w==" 300 crossorigin="anonymous" 301 referrerpolicy="no-referrer" 302 onload="loadSearch('', 'docs')" 303 async></script>
303 304 </body> 305</html>
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.