2018-09-23 08:04:06 +08:00
# How to Use Homebrew Cask
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
## Frequently Used Commands
2013-11-10 21:36:03 +08:00
2020-11-11 19:12:59 +08:00
Homebrew Cask is implemented as part of Homebrew. All Homebrew Cask commands begin with `brew` , which works for both Casks and Formulae. The most frequently-used commands are:
2013-12-16 05:08:27 +08:00
2021-12-16 08:48:02 +08:00
* `install` — installs the given Cask.
* `uninstall` — uninstalls the given Cask.
* `reinstall` — reinstalls the given Cask.
* `list --casks` — lists installed Casks.
2013-12-16 05:08:27 +08:00
2014-01-15 22:55:30 +08:00
## Searching for Casks
2013-12-16 05:08:27 +08:00
2018-06-19 19:43:56 +08:00
To search for Casks, use `brew search` . Let’ s see if there’ s a Cask for Google Chrome:
2013-12-16 05:08:27 +08:00
2014-01-15 22:55:30 +08:00
```bash
2018-06-19 19:43:56 +08:00
$ brew search google-chrome
==> Casks
2020-11-11 19:12:59 +08:00
google-chrome google-chrome-beta google-chrome-canary google-chrome-dev
2014-01-15 22:55:30 +08:00
```
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
## Installing Casks
2013-04-29 03:20:03 +08:00
2020-11-11 19:12:59 +08:00
The command `brew install` accepts one or multiple Cask tokens. Let’ s try to install Google Chrome:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
2020-11-11 19:12:59 +08:00
$ brew install google-chrome
2014-01-15 22:55:30 +08:00
==> Downloading https://dl.google.com/chrome/mac/stable/GGRO/googlechrome.dmg
2020-11-11 19:12:59 +08:00
######################################################################## 100.0%
==> Verifying SHA-256 checksum for Cask 'google-chrome'.
==> Installing Cask google-chrome
==> Moving App 'Google Chrome.app' to '/Applications/Google Chrome.app'.
2016-07-17 04:13:02 +08:00
🍺 google-chrome was successfully installed!
2014-01-15 22:55:30 +08:00
```
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
## Uninstalling Casks
Easy peasy:
```bash
2020-11-11 19:12:59 +08:00
$ brew uninstall google-chrome
2014-01-15 22:55:30 +08:00
```
2016-06-01 03:23:21 +08:00
This will both uninstall the Cask and remove applications which were moved to `/Applications` .
2014-01-15 22:55:30 +08:00
## Other Commands
2021-12-16 08:48:02 +08:00
* `info` — displays information about the given Cask.
* `fetch` — downloads remote application files for the given Cask to the local cache (with `--force` , re-download even if already cached).
* `--cache` — displays the path to Homebrew's local cache.
* `doctor` — checks for configuration issues.
* `style` — checks Cask style using RuboCop.
* `home` — opens the homepage of the given Cask; or with no arguments, the Homebrew project page.
* `uninstall --zap` — try to remove *all* files associated with a Cask (may include resources shared with other applications).
* `outdated` — lists all outdated Casks.
* `upgrade` — updates all outdated Casks.
2014-01-15 22:55:30 +08:00
The following commands are for Cask authors:
2013-04-29 03:20:03 +08:00
2021-12-16 08:48:02 +08:00
* `audit` — verifies installability of Casks.
* `cat` — dumps the given Cask to the standard output.
* `create --cask` — creates a Cask and opens it in an editor.
* `edit` — edits the given Cask.
2013-04-29 03:20:03 +08:00
2014-02-24 21:06:46 +08:00
The following aliases and abbreviations are provided for convenience:
2015-09-07 21:33:37 +08:00
* `ls` — `list`
* `-S` — `search`
* `rm` , `remove` — `uninstall`
* `dr` — `doctor`
2020-11-11 19:12:59 +08:00
* `abv` — `info`
* `homepage` — `home`
2014-02-24 21:06:46 +08:00
2015-10-23 12:29:12 +08:00
## Tab Completion
2020-11-11 19:12:59 +08:00
Homebrew Cask comes with `bash` and `zsh` completion for the `brew` command.
2015-10-23 12:29:12 +08:00
2018-06-22 22:09:22 +08:00
See https://docs.brew.sh/Shell-Completion for more information.
2015-10-23 12:29:12 +08:00
2018-06-22 22:09:22 +08:00
`fish` completions can be installed with:
2015-10-23 12:29:12 +08:00
```bash
2018-06-22 22:09:22 +08:00
$ brew install brew-cask-completion
2015-10-23 12:29:12 +08:00
```
2013-04-29 03:20:03 +08:00
## Inspecting Installed Casks
2016-01-11 20:00:37 +08:00
List all installed Casks:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
2020-11-11 19:12:59 +08:00
$ brew list --casks
2017-12-06 07:28:33 +08:00
atom google-chrome 1password
2014-01-15 22:55:30 +08:00
```
2013-04-29 03:20:03 +08:00
2020-11-11 19:12:59 +08:00
With `--full-name` the Tap name will also be included, _e.g._ : `purple/monkey/dishwasher` for the Cask `dishwasher` installed from the Tap `purple/monkey` .
2021-05-04 11:30:14 +08:00
Given an installed Cask, `brew list --casks <cask_name>` lists the staged files.
2020-11-11 19:12:59 +08:00
2014-01-15 22:55:30 +08:00
Show details about a specific Cask:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
2020-11-11 19:12:59 +08:00
$ brew info keepingyouawake
Error: No available formula with the name "keepingyouawake"
Found a cask named "keepingyouawake" instead.
keepingyouawake: 1.5.2 (auto_updates)
https://keepingyouawake.app/
/usr/local/Caskroom/keepingyouawake/1.5.2 (129B)
From: https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/keepingyouawake.rb
2016-08-15 07:35:03 +08:00
==> Name
2020-11-11 19:12:59 +08:00
KeepingYouAwake
==> Description
Prevents your computer from going to sleep
2016-08-15 07:35:03 +08:00
==> Artifacts
2020-11-11 19:12:59 +08:00
KeepingYouAwake.app (App)
2014-01-15 22:55:30 +08:00
```
2013-04-29 03:20:03 +08:00
## Updating/Upgrading Casks
2020-11-11 19:12:59 +08:00
Since the Homebrew Cask repository is a Homebrew Tap, you’ ll pull down the latest Casks every time you issue the regular Homebrew command `brew update` . You can check for outdated Casks with `brew outdated` and install the outdated Casks with `brew upgrade` . Many applications update themselves, so their Casks are ignored by `brew outdated` and `brew upgrade` . This behaviour can be overridden by adding `--greedy` to the command.
2013-04-29 03:20:03 +08:00
2018-09-23 08:04:06 +08:00
## Updating/Upgrading the Homebrew Cask Tool
2014-01-15 22:55:30 +08:00
2018-09-23 08:04:06 +08:00
Homebrew [automatically taps and keeps Homebrew Cask updated ](https://github.com/Homebrew/homebrew-cask/pull/15381 ). `brew update` is all that is required.
2014-01-15 22:55:30 +08:00
## Additional Taps (optional)
2018-09-23 08:04:06 +08:00
The primary Homebrew Cask Tap includes most of the Casks that a typical user will be interested in. There are a few additional Taps where we store different kinds of Casks.
2014-01-15 22:55:30 +08:00
| Tap name | description |
| -------- | ----------- |
2020-11-11 19:12:59 +08:00
| [Homebrew/cask-versions ](https://github.com/Homebrew/homebrew-cask-versions ) | contains alternate versions of Casks (_e.g._ betas, nightly releases, old versions)
2018-05-22 03:21:38 +08:00
| [Homebrew/cask-fonts ](https://github.com/Homebrew/homebrew-cask-fonts ) | contains Casks that install fonts
| [Homebrew/cask-drivers ](https://github.com/Homebrew/homebrew-cask-drivers ) | contains Casks that install drivers for various devices
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
You can tap any of the above with a `brew tap` command:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
$ brew tap < tap_name >
```
2015-09-16 06:24:11 +08:00
after which, Casks from the new Tap will be available to `search` or `install` just like Casks from the main Tap. `brew update` will automatically keep your new Tap up to date.
2014-01-15 22:55:30 +08:00
2020-11-11 19:12:59 +08:00
You may also specify a fully-qualified Cask token (which includes the Tap) for any `brew` command. This will implicitly add the Tap if you have not previously added it with `brew tap` :
2014-01-15 22:55:30 +08:00
```bash
2020-11-11 19:12:59 +08:00
$ brew install homebrew/cask-fonts/font-symbola
2014-01-15 22:55:30 +08:00
```
2013-04-29 03:20:03 +08:00
## Options
2020-11-11 19:12:59 +08:00
`brew` accepts a number of options:
2014-01-06 04:30:53 +08:00
2021-12-16 08:48:02 +08:00
* `--version` : print version and exit.
* `--debug` : output debug information.
* `--no-binaries` : skip symlinking executable binaries into `/usr/local/bin` .
* `--require-sha` : abort installation of Cask if no checksum is defined.
2021-12-23 08:14:04 +08:00
* `--no-quarantine` : [disable Apple’ s quarantining ](https://docs.brew.sh/FAQ#why-cant-i-open-a-mac-app-from-an-unidentified-developer ) for the specific app.
2020-11-11 19:12:59 +08:00
* `--language=<iso-language>[,<iso-language> ... ]` : changes the language of the Cask to be installed. The first matching language is used, otherwise it uses the default language of the Cask.
2014-01-06 04:30:53 +08:00
2020-11-11 19:12:59 +08:00
You can also modify the default installation locations used when issuing `brew install` :
2013-12-14 17:07:26 +08:00
2017-03-20 07:06:16 +08:00
* `--appdir=/my/path` changes the path where the applications will be moved. Default is `/Applications` .
* `--fontdir=/my/path` changes the path for Fonts. Default is `~/Library/Fonts` .
2014-01-28 23:17:50 +08:00
2020-11-11 19:12:59 +08:00
See `man brew` for the other default installation locations and the flags to change them.
To make these settings persistent, you might want to add the following line to your `.profile` , `.bash_profile` or `.zprofile` :
2013-04-29 03:20:03 +08:00
```bash
2013-12-14 17:10:50 +08:00
# Specify your defaults in this environment variable
2017-05-25 13:29:09 +08:00
export HOMEBREW_CASK_OPTS="--appdir=~/Applications --fontdir=/Library/Fonts"
2013-12-14 17:07:26 +08:00
```
2013-04-29 03:20:03 +08:00
2015-09-16 06:24:11 +08:00
Note that you still can override the environment variable `HOMEBREW_CASK_OPTS` by _explicitly_ providing options in the command line:
2013-04-29 03:20:03 +08:00
2013-12-14 17:07:26 +08:00
```bash
2016-06-02 05:31:35 +08:00
# Will force the Chrome app to be moved to /Applications
2016-06-01 03:23:21 +08:00
# even though HOMEBREW_CASK_OPTS specified ~/Applications
2020-11-11 19:12:59 +08:00
$ brew install --appdir="/Applications" google-chrome
2013-04-29 03:20:03 +08:00
```
2014-01-15 22:55:30 +08:00
## Other Ways to Specify a Cask
2020-11-11 19:12:59 +08:00
Most `brew` commands can accept a Cask token as an argument. As described above, the token on the command line can take the form of:
2014-01-15 22:55:30 +08:00
2020-11-11 19:12:59 +08:00
* A simple token, _e.g._ : `google-chrome` .
* A fully-qualified token which includes the Tap, _e.g._ : `homebrew/cask/google-chrome` .
2014-01-15 22:55:30 +08:00
2020-11-11 19:12:59 +08:00
`brew` also accepts three other forms as arguments:
2014-01-15 22:55:30 +08:00
2020-11-11 19:12:59 +08:00
* A path to a Cask file, _e.g._ : `/usr/local/Library/Taps/homebrew/homebrew-cask/Casks/google-chrome.rb` .
* A `curl` -retrievable URI to a Cask file, _e.g._ : `https://raw.githubusercontent.com/Homebrew/homebrew-cask/f25b6babcd398abf48e33af3d887b2d00de1d661/Casks/google-chrome.rb` .
2022-10-22 05:28:02 +08:00
* A file in the current working directory, _e.g._ : `my-modified-google-chrome.rb` . Note that matching Tapped Cask tokens will be preferred over this form when there is a conflict. To force the use of a Cask file in the current directory, specify a pathname with slashes, _e.g._ : `./google-chrome.rb` .
2014-01-15 22:55:30 +08:00
2014-06-03 22:21:42 +08:00
The last three forms are intended for users who wish to maintain private Casks.
2014-01-15 22:55:30 +08:00
## Taps
2013-04-29 03:20:03 +08:00
2015-09-16 06:24:11 +08:00
You can add Casks to your existing (or new) Taps: just create a directory named `Casks` inside your Tap, put your Cask files there, and everything will just work.