Tips for the Updating Homebrew Woes

Sometimes you run into something that requires you to update your installed packages. And then... you groan. Why? Because you know that once you attempt to update something, a gigantic can of worms will BURST open. Aaaand you know you are about to sink 3-5 hours updating packages, fixing dependencies, the whole nine.

To update brew and installed packages, you usually should only have to do the following commands (1):

1  brew update    # updates brew itself
2  brew upgrade  # upgrades all brew installed packages to latest versions

If you are lucky that day, it will work without a hitch! If not, here are some tips:

0.  The doctor is your best friend

---

Issue the "brew doctor" command. The doc will tell you what's wrong. Heed the doctor's orders and it will go a long way to reduce frustration.

1.  Make sure your brew --prefix directory is owned by you

---

At some point, something will mess with the ownership and permissions on this directory (typically /usr/local) and brew will be unable to write to it. The following command will usually remedy the problem (2):

1  sudo chown -R $(whoami) /usr/local

This command will run as super user and recursively change ownership of that directory and its contents to you, the local user.

2.  A hosed brew installation should be reset

---

Your brew installation may just be completely screwed from the onset. For instance, when you attempt a brew update you may get an error stating (among other things) that "The following untracked working tree files would be overwritten by merge." In this case, reset your brew installation to the master (3):

1  cd $(brew --prefix)
2  git fetch origin
3  git reset --hard origin/master

3.  Update your Xcode installation and/or Command Line Tools for Xcode (CLT)

---

Homebrew depends on stuff Xcode/CLT installs. Other packages Homebrew installs depend on stuff Xcode/CLT installs. Updating it is usually a good idea. If you do this by installing Xcode, you still have to do a few more things:

1. Install Xcode from the App Store
2. Launch Xcode
3. Accept the License Agreement (most important step, otherwise Xcode is a dud)
4. Go to Preferences > Downloads
5. Install/Update Command Line Tools

If you see a message like "error: /usr/include/zlib.h: No such file or directory" when brewing, that usually means you didn't do steps 2-5 listed above. Get at it.

I hope these tips save some of you a bit of time and hours of your life back!

Sources / References

---

1. Homebrew FAQ
2. Homebrew Troubleshooting
3. Reverting to Master Branch

Good Links

---

Homebrew Troubleshooting
Homebrew and Python
Homebrew Homepage