brew/docs/Troubleshooting.md

---
last_review_date: "1970-01-01"
---

# Troubleshooting

**Run `brew update` twice and `brew doctor` (and fix all the warnings) *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

* Read through the list of [Common Issues](Common-Issues.md).

## Check to see if the issue has been reported

* Search the appropriate issue tracker to see if someone else has already reported the same issue:
  * [Homebrew/homebrew-core issue tracker](https://github.com/Homebrew/homebrew-core/issues) (formulae)
  * [Homebrew/homebrew-cask issue tracker](https://github.com/Homebrew/homebrew-cask/issues) (casks)
  * [Homebrew/brew issue tracker](https://github.com/Homebrew/brew/issues) (`brew` itself)
* If the formula or cask that has failed to install is part of a non-Homebrew tap, then check that tap's issue tracker instead.
* Search the [Homebrew discussion forum](https://github.com/orgs/Homebrew/discussions) or [Discourse archive](https://discourse.brew.sh/) to see if any discussions have started about the issue.

## Create an issue

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

1. Collect debugging information:
  * If you have a problem with installing a formula: run `brew gist-logs <formula>` (where `<formula>` is the name of the formula) to upload the logs to a new [Gist](https://gist.github.com).
  * If your have a non-formula problem: collect the output of `brew config` and `brew doctor`.

1. Create a new issue on the issue tracker for [Homebrew/homebrew-core](https://github.com/Homebrew/homebrew-core/issues/new/choose), [Homebrew/homebrew-cask](https://github.com/Homebrew/homebrew-cask/issues/new/choose) or [Homebrew/brew](https://github.com/Homebrew/brew/issues/new/choose) and follow the instructions:
  * Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS or Linux you are using. For example, if a formula fails to build, title your issue "\<formula> failed to build on \<platform>", where *\<formula>* is the name of the formula that failed to build, and *\<platform>* is the name and version of macOS or Linux you are using.
  * Include the URL provided by `brew gist-logs <formula>` (if applicable) plus links to any additional Gists you may have created.
  * Include the output of `brew config` and `brew doctor`.
Add a `last_reviewed_date` to docs metadata - At the AGM we formed an ad-hoc documentation working group. - One of our ideas was that we should have a last reviewed date for documentation, so that we can periodically implement a review mechanism (GitHub Actions posts to Slack for a regular documentation outdatedness check?) to track how old docs are and ensure they're still relevant. - This is a first step towards that goal, by adding a `last_review_date` to the metadata of all docs with a date of earlier than Homebrew's inception because everything needs reviewing so that we start from a good base! 2025-02-03 10:59:02 +00:00			`---`
			`last_review_date: "1970-01-01"`
			`---`

Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`# Troubleshooting`
Troubleshooting: don't report the update issue plz 2015-08-07 12:20:37 +01:00
Update Linuxbrew references to Homebrew on Linux This is a clearer branding for us to use. Also, as part of testing this, make some fixes to Jekyll in the docs folder. Fixes #5835 2019-03-12 20:13:38 +00:00			*Run `brew update` twice and `brew doctor` (and fix all the warnings) before* creating an issue!**
restore the more forceful introduction to the Troubleshooting doc 2016-11-07 18:15:10 +00:00
			`This document will help you check for common issues and make sure your issue has not already been reported.`
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00
			`## Check for common issues`
revise troubleshooting doc 2016-11-06 18:15:58 +00:00
Update Troubleshooting.md 2021-08-25 13:05:35 -04:00			`* Read through the list of [Common Issues](Common-Issues.md).`
put troubleshooting steps in order of specificity 2016-11-06 17:43:49 +00:00
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`## Check to see if the issue has been reported`
revise troubleshooting doc 2016-11-06 18:15:58 +00:00
Update Troubleshooting.md 2021-08-25 13:05:35 -04:00			`* Search the appropriate issue tracker to see if someone else has already reported the same issue:`
			`* [Homebrew/homebrew-core issue tracker](https://github.com/Homebrew/homebrew-core/issues) (formulae)`
			`* [Homebrew/homebrew-cask issue tracker](https://github.com/Homebrew/homebrew-cask/issues) (casks)`
			* [Homebrew/brew issue tracker](https://github.com/Homebrew/brew/issues) (`brew` itself)
			`* If the formula or cask that has failed to install is part of a non-Homebrew tap, then check that tap's issue tracker instead.`
docs: hyperlink updates plus some reformatting 2022-12-03 16:44:33 -05:00			`* Search the [Homebrew discussion forum](https://github.com/orgs/Homebrew/discussions) or [Discourse archive](https://discourse.brew.sh/) to see if any discussions have started about the issue.`
revise troubleshooting doc 2016-11-06 18:15:58 +00:00
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`## Create an issue`
revise troubleshooting doc 2016-11-06 18:15:58 +00:00
			`If your problem hasn't been solved or reported, then create an issue:`

Update Troubleshooting.md 2021-08-25 13:05:35 -04:00			`1. Collect debugging information:`
			* If you have a problem with installing a formula: run `brew gist-logs <formula>` (where `<formula>` is the name of the formula) to upload the logs to a new [Gist](https://gist.github.com).
			* If your have a non-formula problem: collect the output of `brew config` and `brew doctor`.
Update Linuxbrew references to Homebrew on Linux This is a clearer branding for us to use. Also, as part of testing this, make some fixes to Jekyll in the docs folder. Fixes #5835 2019-03-12 20:13:38 +00:00
Update Troubleshooting.md 2021-08-25 13:05:35 -04:00			`1. Create a new issue on the issue tracker for [Homebrew/homebrew-core](https://github.com/Homebrew/homebrew-core/issues/new/choose), [Homebrew/homebrew-cask](https://github.com/Homebrew/homebrew-cask/issues/new/choose) or [Homebrew/brew](https://github.com/Homebrew/brew/issues/new/choose) and follow the instructions:`
docs: various additions & changes 2023-09-05 00:58:57 -04:00			`* Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS or Linux you are using. For example, if a formula fails to build, title your issue "\<formula> failed to build on \<platform>", where \<formula> is the name of the formula that failed to build, and \<platform> is the name and version of macOS or Linux you are using.`
Update Troubleshooting.md 2021-08-25 13:05:35 -04:00			* Include the URL provided by `brew gist-logs <formula>` (if applicable) plus links to any additional Gists you may have created.
			* Include the output of `brew config` and `brew doctor`.