mirrors/brew
1
0
Fork 0
mirror of https://github.com/Homebrew/brew.git synced 2025-07-14 16:09:03 +08:00
Code Issues Packages Projects Releases Wiki Activity
brew/docs/Troubleshooting.md
Mike McQuaid 978c121276 Tweak troubleshooting docs and issue template 
- Note that Homebrew Cask issues should be filed elsewhere.
- Make `brew`/homebrew-core issue differential in simpler language
- Tell people to fix all `brew doctor` issues
- Refer to the issue checklist and make it even more clear and prominent
  that we may close it out immediately if they don't use it.
- Note that proposed new issues should be widely relevant.
- Don't tell people they need to `brew cask install java`; we handle
  this in most places with a Java requirement and probably want issues
  filed where we don't.
- Remove reference to Homebrew Dupes and replace with reference to
  Homebrew Cask to try and get people filing stuff there instead.

Fixes #2608
2017-05-09 15:21:28 +01:00

2.3 KiB
Raw Blame History

Troubleshooting

Run brew update twice and brew doctor before creating an issue!

This document will help you check for common issues and make sure your issue has not already been reported.

Check for common issues

Follow these steps to fix common problems:

  • Run brew update twice.
  • Run brew doctor and fix all the warnings (outdated Xcode/CLT and unbrewed dylibs are very likely to cause problems).
  • Check that Command Line Tools for Xcode (CLT) and Xcode are up to date.
  • If commands fail with permissions errors, check the permissions of /usr/local's subdirectories. If you’re unsure what to do, you can run cd /usr/local && sudo chown -R $(whoami) bin etc include lib sbin share var Frameworks.
  • Read through the Common Issues.

Check to see if the issue has been reported

  • Search the issue tracker to see if someone else has already reported the same issue.
  • Make sure you search issues on the correct repository. If a formula that has failed to build is part of a tap like homebrew/science or a cask is part of caskroom/cask check those issue trackers instead.

Create an issue

If your problem hasn't been solved or reported, then create an issue:

  1. Upload debugging information to a Gist:
  • If you had a formula-related problem: run brew gist-logs <formula> (where <formula> is the name of the formula).
  • If you encountered a non-formula problem: upload the output of brew config and brew doctor to a new Gist.
  1. Create a new issue.
  • Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS you are using. For example, if a formula fails to build, title your issue "<formula> failed to build on <10.x>", where "<formula>" is the name of the formula that failed to build, and "<10.x>" is the version of macOS you are using.
  • Include the URL output by brew gist-logs <formula> (if applicable).
  • Include links to any additional Gists you may have created (such as for the output of brew config and brew doctor).