Skip to content
This repository has been archived by the owner on Sep 1, 2021. It is now read-only.

Installation

Jump to bottom
adamv edited this page Mar 9, 2011 · 90 revisions

The default and recommended installation:

1. ruby -e "$(curl -fsSLk https://gist.github.com/raw/323731/install_homebrew.rb)"
2. Install Xcode.

NOTE: This method might not work for machines managed with Directory Services.

You should read the rest of this wiki, but it’s up to you.

Requirements

2 Not all brews have CPU or OS requirements, but you can assume you will have trouble if you don’t conform. Also, you can find PowerPC and Tiger branches from other users in the fork tree.

3 Homebrew itself does not depend on Xcode and not all formulae require Xcode. Homebrew will still attempt to install formulae if Xcode is not installed; this is so people can create custom Homebrew installations that eg. only install binaries.

4 Software that tries to build Java bindings (Subversion, Berkeley-DB, Cmake, etc.) will require an additional JDK download if using Apple’s 1.6.0_22 JRE update. The latest versions are “Update 4” for 10.6 and “Update 9” for 10.5.

We recommend you delete /usr/local/include and /usr/local/lib

Most likely you’ve done a bit of “homebrew” installation already. We’ve had a lot of bug reports that are first inexplicable and later it turns out that it’s because the user has some of their own libs and headers in /usr/local. Homebrew can’t stop gcc and other build tools from using these libraries. Before you install we strongly recommend you delete the contents of these two directories.

If in doubt, don’t delete this stuff, but be aware that this may cause build issues.

Location

You can put Homebrew anywhere, but some choices are better than others:

  1. Avoid directories that contain spaces
    Homebrew tries to make this work, but some build scripts that formulae execute don’t like spaces.
  2. Avoid /opt/local and /sw
    These directories are already used by MacPorts and Fink. Some tools and build scripts expect to find things there and get confused if something else is there instead.

Do yourself a favour and pick /usr/local

  1. It’s easier
    /usr/local/bin is already in your PATH.
  2. It’s easier
    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.
  3. It’s safe
    Apple has conformed to POSIX and left this directory for us. Which means there is no /usr/local directory by default, so there is no need to worry about messing up existing tools.
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 trivial to tell gem to look in non-standard directories for headers and dylibs. If you choose /usr/local, everything “just works!”

Installing to /usr/local for Developers

Homebrew will happily coexist with any existing stuff you have installed in /usr/local.

This script is the recommended way to install to /usr/local. It does a lot of checks, and makes the minimum of permissions changes to ensure you can brew without sudo.

If you’re the DIY sort and know what you are doing then you can just run this:

sudo chown -R $USER /usr/local
curl -Lsf http://github.com/mxcl/homebrew/tarball/master | tar xz --strip 1 -C/usr/local

If you install via tarball and would like to track the upstream source repository via git after the fact you can do so easily. This works even if you chose to use brew to install git.

brew install git

Note you have to already have Git installed for these steps to work: 
git clone http://github.com/mxcl/homebrew.git /tmp/homebrew

You should actually create a fork of the homebrew repository and maintain your own fork

git clone http://github.com/YOURGITHUBUSERNAME/homebrew.git /tmp/homebrew
mv /tmp/homebrew/.git /usr/local/
rm -rf /tmp/homebrew
cd /usr/local
git status

Installing anywhere else

Just grab the master tarball and extract it anywhere you like. Homebrew is self-contained and will install its brews into its extracted directory. Just make sure you add the bin directory to your PATH, or always call the brew tool via its full path.

Sudo

tl;dr Sudo is dangerous, and you installed TextMate.app without sudo anyway.

Homebrew is designed to work without using sudo. You can decide to use it but we strongly recommend not to do so. If you have used sudo and run into a bug then it is likely to be the cause. Please don’t file a bug report unless you can reproduce it after reinstalling Homebrew from scratch without using sudo.

You should only ever sudo a tool you trust. Of course, you can trust Homebrew ;) But do you trust the multi-megabyte Makefile that Homebrew runs? Developers often understand C++ far better than they understand make syntax. It’s too high a risk to sudo such stuff. It could break your base system, or alter it subtly.

And indeed, I have seen some build scripts try to modify /usr even when the prefix was specified as something else entirely.

Did you chown root /Applications/TextMate.app? Probably not. So is it that important to chown root wget?

Uninstallation

cd `brew --prefix`
rm -rf Cellar
brew prune
rm -rf Library .git .gitignore bin/brew README.md share/man/man1/brew
rm -rf ~/Library/Caches/Homebrew

It is worth noting that if you installed somewhere like /usr/local then these uninstallation steps will leave that directory exactly like it was before Homebrew was installed. Unless you manually (ie. without brew) added new stuff there, in which case those things will still be there too.

Alternate Installation Style

You can also install Homebrew into eg. ~/Developer (or ~/.homebrew) and then symlink the brew command into /usr/local/bin.

Everything will install into ~/Developer, but your brew command is still in the path.

Multiple installations

Create a Homebrew installation wherever you extract the tarball. Whichever brew command is called is where the packages will be installed. You can use this as you see fit, eg. a system set of libs in /usr/local and tweaked formulae for development in ~/homebrew.

Clone this wiki locally