homebrew-cask Documentation

File: README.md Copy Chapter

Homebrew Cask

“To install, drag this icon…” no more!

Homebrew Cask extends Homebrew and brings its elegance, simplicity, and speed to the installation and management of prebuilt software artifacts distributed by upstream vendors, including GUI applications, CLI tools, fonts, plugins, and other packaged software.

We do this by providing a friendly CLI workflow for the administration of these artifacts on macOS and Linux.

Let’s try it! Copy Chapter

To start using Homebrew Cask, you just need Homebrew installed.

Slower, now:

% brew install alfred
==> Fetching downloads for: alfred
✔︎ Cask alfred (5.7.2,2312)                                           Verified      5.6MB/  5.6MB
==> Installing Cask alfred
==> Moving App 'Alfred 5.app' to '/Applications/Alfred 5.app'
🍺  alfred was successfully installed!

And there we have it. An application installed with one quick command: no clicking, no dragging, no dropping.

Learn More Copy Chapter

• Find basic documentation on using Homebrew Cask in USAGE.md.
• Want to contribute a cask? Awesome! See CONTRIBUTING.md.
• More project-related details and discussion are available in the documentation.

Reporting Bugs Copy Chapter

If you ignore this guide, your issue may be closed without review

Before reporting a bug, run brew update-reset && brew update and try your command again. This is a fix-all that will reset the state of all your taps, ensuring the problem isn’t an outdated setup on your side.

If your issue persists, search for it before opening a new one. If you find an open issue and have any new information, add it in a comment. If you find a closed issue, try the solutions there.

If the issue is still not solved, see the guides for common problems:

• Examples of common errors and their solutions
  • curl error
  • Permission denied error
  • Checksum does not match error
  • source is not there error
  • wrong number of arguments error
• App isn’t included in upgrade
• The app can’t be opened because it is from an unidentified developer
• My problem isn’t listed

Requests Copy Chapter

• Issues requesting new casks will be closed. If you want a cask added to the main repositories, submit a pull request.
• For a feature request, use this template.

Questions? Wanna chat? Copy Chapter

We’re really rather friendly! Here are the best places to talk about the project:

• Open an issue.
• Join us on GitHub discussions (forum).

License Copy Chapter

Code is under the BSD 2 Clause (NetBSD) license.

File: doc/reporting_bugs/error_examples.md Copy Chapter

Examples of common errors and their solutions

`curl` error:

If the error output includes something like

curl: (22) The requested URL returned error: 403 Forbidden

the problem was with the downloading itself (see how the error came from curl). Homebrew Cask itself is fine and the problem is generally one of:

1. Software vendor or the file in their server is down.
2. Cask is outdated.
3. A problem in your setup or connection.

How to fix

`Permission denied` error:

If the error output includes something like

Error: Permission denied - (/usr/local/Caskroom/someapp/0.1/Someapp.app, /Applications/Someapp.app)

the problem isn’t with Homebrew Cask itself, but some permissions on your system.

How to fix

`Checksum does not match` error

If the error output includes something like

Error: Checksum for Cask 'your-cask' does not match.

Expected: 3dbc6c2205af35db5370c7642b9a2b833668880569b9c64a7f5a670bf9911130
Actual: 526d747d99a93b760f7965e25a57ed61de9b93d566a0ba0c5f1c7e83719b20fd

either your download was incomplete/corrupt or the cask is outdated.

How to fix

`source is not there` error

If the error output includes something like

It seems the App source '/usr/local/Caskroom/someapp/0.1/Someapp.app' is not there.

the directory structure inside the app’s archive changed in some way. It must be fixed in Homebrew Cask.

How to fix

`wrong number of arguments` error

If the error output includes something like

Error: wrong number of arguments (1 for 4)

it’s likely the software you’re trying to install is incompatible with your macOS version.

How to fix

Unlisted reason

If your issue isn’t listed here, go back and pick My problem isn’t listed.

File: doc/faq/closing_issues_without_review.md Copy Chapter

If your issue was closed without review

Both the reporting bugs section of the readme and the bug report issue template you need to fill before opening an issue warn that if the instructions aren’t followed, your issue may be closed without review.

You might have been redirected to this document if it was apparent to a maintainer that was the case. We worked hard on those guides to keep things running smoothly, so we ask you go back and follow them. It is OK to open a new issue for that.

If the maintainer was wrong in closing your issue, please do reply stating why! Closing an issue does not mean the conversation is over. If the guides themselves were unclear, help us improve them! Open first an issue or pull request stating what you found confusing and only then your other issue.

We understand sometimes users are tired and don’t want to sift through a guide to make what they feel is a simple bug report. But when each user ignores the guides to save a few minutes, maintainers lose hours and get fatigued. Dealing with the same solved and documented problems leads to maintainer burnout and wasted hours. Those would be better spent improving Homebrew Cask itself and fixing real bugs. We ask you take that into consideration.

Thank you for understanding and taking the time to make a correct report. The whole team appreciates it.