2014-10-26 14:54:36 +00:00
# FAQ
2017-01-04 10:53:21 +00:00
## How do I update my local packages?
2014-10-26 14:54:36 +00:00
First update the formulae and Homebrew itself:
brew update
You can now find out what is outdated with:
brew outdated
Upgrade everything with:
2015-07-16 10:37:17 +02:00
brew upgrade
2014-10-26 14:54:36 +00:00
Or upgrade a specific formula with:
2017-03-25 22:53:33 -04:00
brew upgrade < formula >
2014-10-26 14:54:36 +00:00
2017-01-04 10:53:21 +00:00
## How do I stop certain formulae from being updated?
2014-12-02 03:25:31 +00:00
To stop something from being updated/upgraded:
2017-03-25 22:53:33 -04:00
brew pin < formula >
2014-12-02 03:25:31 +00:00
To allow that formulae to update again:
2017-03-25 22:53:33 -04:00
brew unpin < formula >
2014-12-02 03:25:31 +00:00
2018-10-05 17:23:22 -04:00
Note that pinned, outdated formulae that another formula depends on need to be upgraded when required as we do not allow formulae to be built against non-latest versions.
2017-08-11 17:23:11 +01:00
2017-01-04 10:53:21 +00:00
## How do I uninstall old versions of a formula?
2014-10-26 14:54:36 +00:00
By default, Homebrew does not uninstall old versions of a formula, so
over time you will accumulate old versions. To remove them, simply use:
2017-03-25 22:53:33 -04:00
brew cleanup < formula >
2014-10-26 14:54:36 +00:00
or clean up everything at once:
brew cleanup
2017-03-18 17:45:12 -04:00
or to see what would be cleaned up:
2014-10-26 14:54:36 +00:00
brew cleanup -n
2017-01-04 10:53:21 +00:00
## How do I uninstall Homebrew?
2015-04-08 19:14:43 +08:00
To uninstall Homebrew, paste the command below in a terminal prompt.
2017-03-25 22:53:33 -04:00
```sh
2015-04-08 19:14:43 +08:00
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/uninstall)"
```
2017-03-25 22:53:33 -04:00
2015-04-08 19:14:43 +08:00
Download the [uninstall script ](https://raw.githubusercontent.com/Homebrew/install/master/uninstall )
and run `./uninstall --help` to view more uninstall options.
2014-10-26 14:54:36 +00:00
2017-01-04 10:53:21 +00:00
## How do I uninstall a formula?
2014-10-26 14:54:36 +00:00
If you do not uninstall all of the versions that Homebrew has installed,
Homebrew will continue to attempt to install the newest version it knows
2018-04-07 21:07:24 +01:00
about when you run `brew upgrade` . This can be surprising.
2014-10-26 14:54:36 +00:00
2018-10-05 17:23:22 -04:00
To remove a formula entirely, you may run `brew uninstall --force <formula>` .
2014-10-26 14:54:36 +00:00
2015-03-13 20:48:44 -07:00
Be careful as this is a destructive operation.
2014-10-26 14:54:36 +00:00
2017-01-04 10:53:21 +00:00
## Where does stuff get downloaded?
2014-10-26 14:54:36 +00:00
brew --cache
2016-08-08 00:09:56 +01:00
Which is usually: `~/Library/Caches/Homebrew`
2014-10-26 14:54:36 +00:00
2017-01-04 10:53:21 +00:00
## My Mac `.app`s donā t find `/usr/local/bin` utilities!
2017-08-19 17:08:07 -07:00
GUI apps on macOS donā t have `/usr/local/bin` in their `PATH` by
2018-10-05 17:23:22 -04:00
default. If youā re on Mountain Lion or later, you can fix this by
2017-08-19 17:08:07 -07:00
running `sudo launchctl config user path "/usr/local/bin:$PATH"` and
2017-08-23 15:56:00 -07:00
then rebooting, as documented in `man launchctl` . Note that this sets
2018-10-05 17:23:22 -04:00
the launchctl PATH for *all users* . For earlier versions of macOS, see
2017-08-19 17:08:07 -07:00
[this page ](https://developer.apple.com/legacy/library/qa/qa1067/_index.html ).
2014-10-26 14:54:36 +00:00
2017-01-04 10:53:21 +00:00
## How do I contribute to Homebrew?
2018-10-05 17:23:22 -04:00
Read our [contribution guidelines ](https://github.com/Homebrew/brew/blob/master/CONTRIBUTING.md#contributing-to-homebrew ).
2014-10-26 14:54:36 +00:00
2017-01-04 10:53:21 +00:00
## Why do you compile everything?
2016-02-18 00:15:22 +00:00
Homebrew provides pre-compiled versions for many formulae. These
2018-02-23 19:39:19 +00:00
pre-compiled versions are referred to as [bottles ](Bottles.md ) and are available
2017-02-23 12:09:01 -05:00
at < https: / / bintray . com / homebrew / bottles > .
2014-10-26 14:54:36 +00:00
If available, bottled binaries will be used by default except under the
following conditions:
2017-03-25 22:53:33 -04:00
* Options were passed to the install command, i.e. `brew install <formula>`
will use a bottled version of the formula, but
2018-10-05 17:23:22 -04:00
`brew install --enable-bar <formula>` will trigger a source build.
2014-10-26 14:54:36 +00:00
* The `--build-from-source` option is invoked.
2017-07-20 14:46:35 -04:00
* The environment variable `HOMEBREW_BUILD_FROM_SOURCE` is set
(intended for developers only).
2016-12-07 16:34:52 -06:00
* The machine is not running a supported version of macOS as all
bottled builds are generated only for supported macOS versions.
2014-10-26 14:54:36 +00:00
* Homebrew is installed to a prefix other than the standard
2017-03-18 17:45:12 -04:00
`/usr/local` (although some bottles support this).
2014-10-26 14:54:36 +00:00
We aim to bottle everything.
2017-01-04 10:53:21 +00:00
## How do I get a formula from someone elseā s branch?
2014-10-26 14:54:36 +00:00
2017-03-25 22:53:33 -04:00
```sh
brew install hub
brew update
cd $(brew --repository)
hub pull someone_else
```
2014-10-26 14:54:36 +00:00
Or:
2017-03-25 22:53:33 -04:00
brew pull https://github.com/Homebrew/homebrew-core/pull/1234
2014-10-26 14:54:36 +00:00
2017-01-04 10:53:21 +00:00
## Why does Homebrew prefer I install to `/usr/local`?
2014-10-26 14:54:36 +00:00
1. **Itā s easier** < br > `/usr/local/bin` is already in your
`PATH` .
2. **Itā s easier** < br > Tons of build scripts break if their dependencies
arenā t in either `/usr` or `/usr/local` . We
fix this for Homebrew formulae (although we donā t always test for
it), but youā ll find that many RubyGems and Python setup scripts
break which is something outside our control.
2019-01-03 15:15:35 +00:00
3. **Itā s safe** < br > Apple has assigned this directory for non-system utilities. This means
there are no files in `/usr/local` by default, so there
2018-04-07 21:07:24 +01:00
is no need to worry about messing up existing or system tools.
2014-10-26 14:54:36 +00:00
**If you plan to install gems that depend on
brews then save yourself a bunch of hassle and install to
`/usr/local` !**
It is not always straightforward to tell `gem` to look in non-standard directories for headers and libraries. If you choose `/usr/local` , many things will "just work".
2017-03-18 17:45:12 -04:00
## Why does Homebrew say sudo is bad?
2014-10-26 14:54:36 +00:00
**tl;dr** Sudo is dangerous, and you installed TextMate.app without sudo
anyway.
2018-04-07 21:07:24 +01:00
Homebrew refuses to work using sudo.
You should only ever sudo a tool you trust. Of course, you can trust Homebrew
2018-09-06 15:07:00 +01:00
š But do you trust the multi-megabyte Makefile that Homebrew runs? Developers
2018-04-07 21:07:24 +01:00
often understand C++ far better than they understand make syntax. Itā s too high
a risk to sudo such stuff. It could modify (or upload) any files on your
system.And indeed, weā ve seen some build scripts try to modify `/usr` even when
the prefix was specified as something else entirely.
We use the macOS sandbox to stop this but this doesn't work when run as the `root` user (which also has read and write access to almost everything on the system).
2014-10-26 14:54:36 +00:00
Did you `chown root /Applications/TextMate.app` ? Probably
not. So is it that important to `chown root wget` ?
If you need to run Homebrew in a multi-user environment, consider
creating a separate user account especially for use of Homebrew.
2017-01-04 10:53:21 +00:00
## Why isnā t a particular command documented?
2014-10-26 14:54:36 +00:00
2018-02-23 19:39:19 +00:00
If itā s not in `man brew` , itā s probably an external command. These are documented [here ](External-Commands.md ).
2014-10-26 14:54:36 +00:00
2017-01-04 10:53:21 +00:00
## Why havenā t you pulled my pull request?
2014-10-26 14:54:36 +00:00
If itā s been a while, bump it with a ābumpā comment. Sometimes we miss requests and there are plenty of them. Maybe we were thinking on something. It will encourage consideration. In the meantime if you could rebase the pull request so that it can be cherry-picked more easily we will love you for a long time.
2017-01-04 10:53:21 +00:00
## Can I edit formulae myself?
2017-03-25 22:53:33 -04:00
Yes! Itā s easy! Just `brew edit <formula>` . You donā t have to submit modifications back to `homebrew/core` , just edit the formula as you personally need it and `brew install` . As a bonus `brew update` will merge your changes with upstream so you can still keep the formula up-to-date **with** your personal modifications!
2014-10-26 14:54:36 +00:00
2017-01-04 10:53:21 +00:00
## Can I make new formulae?
2017-04-02 10:14:33 +01:00
Yes! Itā s easy! Just `brew create URL` . Homebrew will then open the formula in
`EDITOR` so you can edit it, but it probably already installs; try it: `brew
install < formula > `. If you encounter any issues, run the command with the
`--debug` switch like so: `brew install --debug <formula>` , which drops you
into a debugging shell.
2014-10-26 14:54:36 +00:00
2017-03-25 22:53:33 -04:00
If you want your new formula to be part of `homebrew/core` or want
2018-02-23 19:39:19 +00:00
to learn more about writing formulae, then please read the [Formula Cookbook ](Formula-Cookbook.md ).
2014-10-26 14:54:36 +00:00
2017-01-04 10:53:21 +00:00
## Can I install my own stuff to `/usr/local`?
2017-03-25 22:53:33 -04:00
Yes, `brew` is designed to not get in your way so you can use it how you
2014-10-26 14:54:36 +00:00
like.
Install your own stuff, but be aware that if you install common
2017-03-18 17:45:12 -04:00
libraries like libexpat yourself, it may cause trouble when trying to
2014-10-26 14:54:36 +00:00
build certain Homebrew formula. As a result `brew doctor` will warn you
about this.
Thus itā s probably better to install your own stuff to the Cellar and
then `brew link` it. Like so:
2017-03-25 22:53:33 -04:00
```sh
2014-10-26 14:54:36 +00:00
$ cd foo-0.1
$ brew diy
2015-12-30 15:53:48 +08:00
./configure --prefix=/usr/local/Cellar/foo/0.1
$ ./configure --prefix=/usr/local/Cellar/foo/0.1
2014-10-26 14:54:36 +00:00
[snip]
$ make & & make install
$ brew link foo
Linking /usr/local/Cellar/foo/0.1⦠17 symlinks created
```
2017-01-04 10:53:21 +00:00
## Why was a formula deleted?
2017-03-25 22:53:33 -04:00
Use `brew log <formula>` to find out! Likely because it had unresolved issues or
2017-01-02 18:29:00 +00:00
our analytics identified it was not widely used.
2014-10-26 14:54:36 +00:00
2017-03-18 17:45:12 -04:00
## Homebrew is a poor name, it's too generic, why was it chosen?
2015-12-06 22:18:16 +00:00
@mxcl was too concerned with the beer theme and didnā t consider that the
2018-09-06 15:07:00 +01:00
project may actually prove popular. By the time he realised it was, it was too
2017-03-18 17:45:12 -04:00
late. However, today, the first Google hit for āhomebrewā is not beer
2018-10-05 17:23:22 -04:00
related ;& #8209 ; )
2014-10-26 14:54:36 +00:00
2017-03-18 17:45:12 -04:00
## What does "keg-only" mean?
2015-06-07 11:49:41 -07:00
It means the formula is installed only into the Cellar; it is not linked
2014-10-26 14:54:36 +00:00
into `/usr/local` . This means most tools will not find it. We donā t do
2015-06-07 11:49:41 -07:00
this for stupid reasons. You can still link in the formula if you need
2014-10-26 14:54:36 +00:00
to with `brew link` .
2017-01-04 10:53:21 +00:00
## How can I specify different configure arguments for a formula?
2017-03-25 22:53:33 -04:00
`brew edit <formula>` and edit the formula. Currently there is no
2015-03-13 20:48:44 -07:00
other way to do this.
2016-10-12 21:38:59 -04:00
2017-01-04 10:53:21 +00:00
## Is there a glossary of terms around?
2016-10-16 11:14:17 +03:00
All your terminology needs can be [found here ](Formula-Cookbook.md#homebrew-terminology ).