mirror of
https://github.com/Homebrew/brew.git
synced 2026-08-12 22:29:27 +04:00
62 lines
2.4 KiB
Markdown
62 lines
2.4 KiB
Markdown
---
|
|
last_review_date: "2026-07-18"
|
|
---
|
|
|
|
# Troubleshooting
|
|
|
|
Use this checklist before creating a Homebrew issue.
|
|
|
|
## Update and diagnose
|
|
|
|
1. Run `brew update`.
|
|
2. Run `brew update` again so the first update cannot leave the failing command on an older Homebrew version.
|
|
3. Run `brew doctor` and read every warning.
|
|
4. Correct warnings that apply to the failing command.
|
|
5. Retry the original command and keep its complete output.
|
|
|
|
Do not apply destructive Git, ownership or permission changes from an old issue report without understanding which files they affect.
|
|
See [Common Issues](Common-Issues.md) for current recovery guidance.
|
|
|
|
## Search existing reports
|
|
|
|
Search the tracker responsible for the failing component:
|
|
|
|
- [`Homebrew/homebrew-core` issues](https://github.com/Homebrew/homebrew-core/issues) for formulae
|
|
- [`Homebrew/homebrew-cask` issues](https://github.com/Homebrew/homebrew-cask/issues) for casks
|
|
- [`Homebrew/brew` issues](https://github.com/Homebrew/brew/issues) for the `brew` command
|
|
- The tap's own tracker for a formula, cask or command from a non-Homebrew tap
|
|
|
|
Also search [Homebrew Discussions](https://github.com/orgs/Homebrew/discussions) for support and related reports.
|
|
The [Discourse archive](https://discourse.brew.sh/) is read-only historical material and will contain outdated instructions.
|
|
|
|
## Collect diagnostic information
|
|
|
|
For a formula installation or build failure, upload its logs:
|
|
|
|
```sh
|
|
brew gist-logs FORMULA
|
|
```
|
|
|
|
For other failures, collect:
|
|
|
|
```sh
|
|
brew config
|
|
brew doctor
|
|
```
|
|
|
|
Remove credentials, private repository URLs and other secrets before publishing terminal output.
|
|
Do not omit warnings merely because they appear unrelated.
|
|
|
|
## Create an issue
|
|
|
|
If the problem is neither resolved nor already reported, use the issue template in the appropriate repository:
|
|
|
|
- [`Homebrew/homebrew-core` issue chooser](https://github.com/Homebrew/homebrew-core/issues/new/choose)
|
|
- [`Homebrew/homebrew-cask` issue chooser](https://github.com/Homebrew/homebrew-cask/issues/new/choose)
|
|
- [`Homebrew/brew` issue chooser](https://github.com/Homebrew/brew/issues/new/choose)
|
|
|
|
Include the command, complete error, relevant `brew config` and `brew doctor` output and the `brew gist-logs` URL when available.
|
|
Use a descriptive title that identifies the package, failure and operating system.
|
|
|
|
See [Creating a Homebrew Issue](Creating-a-Homebrew-Issue.md) for reporting expectations.
|