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 Oct 6, 2010 · 90 revisions

tl;dr

Install in the default and recommended way:

ruby -e "$(curl -fsS http://gist.github.com/raw/323731/install_homebrew.rb)"

Execute that gist and then install Xcode.

 

 

 

 
And now for all the other stuff that you should read, but we’ll forgive you if you don’t (just this once):

Requirements

  • An Intel CPU2
  • OS X Leopard or higher
  • Xcode with X113

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 formula require Xcode. Homebrew will still attempt to install formula if Xcode is not installed; this is so people can create custom Homebrew installations that eg. only install binaries.

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 formula 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 formulas (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

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 are happy to sudo your brews, then just untar into /usr/local:

curl -Lsf http://github.com/mxcl/homebrew/tarball/master | sudo tar xvz --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! Note you have to already have Git installed for these steps to work:

git clone http://github.com/mxcl/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 works with or without sudo.

So it is up to you.

However, 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.

Also:

  1. Did you chown root /Applications/TextMate.app? Probably not. So is it that important to chown root wget?
  2. You can always sudo install specific packages if you like.

Some stuff should be installed chown root. And in those cases install without sudo and then do this:

brew list foo | xargs sudo chown root

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. ~/.homebrew and then symlink the brew command into /usr/local/bin.

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 formula for development in ~/homebrew.

Clone this wiki locally