Manpage.md 51.6 KB
Newer Older
1
brew(1) -- The Missing Package Manager for macOS
2
================================================
3
4
5
6

## SYNOPSIS

`brew` `--version`<br>
7
`brew` *`command`* [`--verbose`|`-v`] [*`options`*] [*`formula`*] ...
8
9
10
11
12
13
14
15

## DESCRIPTION

Homebrew is the easiest and most flexible way to install the UNIX tools Apple
didn't include with macOS.

## ESSENTIAL COMMANDS

Peter Newman's avatar
Peter Newman committed
16
For the full command list, see the [COMMANDS](#commands) section.
17

18
19
With `--verbose` or `--debug`, many commands print extra debugging information. Note that
these options should only appear after a command.
20

Mike McQuaid's avatar
Mike McQuaid committed
21
### `install` *`formula`*:
22

Mike McQuaid's avatar
Mike McQuaid committed
23
Install *`formula`*.
24

25
26
27
*`formula`* is usually the name of the formula to install, but it has other syntaxes which
are listed in the [SPECIFYING FORMULAE](#specifying-formulae) section.

Mike McQuaid's avatar
Mike McQuaid committed
28
### `uninstall` *`formula`*:
29

Mike McQuaid's avatar
Mike McQuaid committed
30
Uninstall *`formula`*.
31

Mike McQuaid's avatar
Mike McQuaid committed
32
### `list`:
33

Mike McQuaid's avatar
Mike McQuaid committed
34
List all installed formulae.
35

Mike McQuaid's avatar
Mike McQuaid committed
36
### `search` (*`text`*|`/`*`text`*`/`):
37

Mike McQuaid's avatar
Mike McQuaid committed
38
Perform a substring search of cask tokens and formula names for *`text`*. If *`text`*
39
is flanked by slashes, it is interpreted as a regular expression.
Mike McQuaid's avatar
Mike McQuaid committed
40
The search for *`text`* is extended online to `homebrew/core` and `homebrew/cask`.
41
If no search term is provided, all locally available formulae are listed.
42

Mike McQuaid's avatar
Mike McQuaid committed
43
## COMMANDS
44

45
### `analytics` [*`subcommand`*]
46

47
If `on` or `off` is passed, turn Homebrew's analytics on or off respectively.
48

49
50
If `state` is passed, display the current anonymous user behaviour analytics
state. Read more at <https://docs.brew.sh/Analytics>.
51

52
53
If `regenerate-uuid` is passed, regenerate the UUID used in Homebrew's
analytics.
54

Mike McQuaid's avatar
Mike McQuaid committed
55
### `cat` *`formula`*
56

Mike McQuaid's avatar
Mike McQuaid committed
57
Display the source of *`formula`*.
58

Mike McQuaid's avatar
Mike McQuaid committed
59
### `cleanup` [*`options`*] [*`formula`*|*`cask`*]
60

61
Remove stale lock files and outdated downloads for all formulae and casks, and
62
remove old versions of installed formulae. If arguments are specified, only do
63
this for the given formulae and casks.
64

Mike McQuaid's avatar
Mike McQuaid committed
65
66
67
68
69
* `--prune`:
  Remove all cache files older than specified *`days`*.
* `-n`, `--dry-run`:
  Show what would be removed, but do not actually remove anything.
* `-s`:
70
  Scrub the cache, including downloads for even the latest versions. Note downloads for any installed formulae or casks will still not be deleted. If you want to delete those too: `rm -rf "$(brew --cache)"`
71
72
* `--prune-prefix`:
  Only prune the symlinks and directories from the prefix and remove no other files.
Mike McQuaid's avatar
Mike McQuaid committed
73
74
75

### `command` *`cmd`*

76
Display the path to the file being used when invoking `brew` *`cmd`*.
Mike McQuaid's avatar
Mike McQuaid committed
77
78
79

### `commands` [*`options`*]

80
Show lists of built-in and external commands.
Mike McQuaid's avatar
Mike McQuaid committed
81

82
83
* `-q`, `--quiet`:
  List only the names of commands without category headers.
Mike McQuaid's avatar
Mike McQuaid committed
84
* `--include-aliases`:
85
  Include aliases of internal commands.
Mike McQuaid's avatar
Mike McQuaid committed
86
87
88

### `config`

89
90
Show Homebrew and system configuration info useful for debugging. If you file a
bug report, you will be required to provide this information.
Mike McQuaid's avatar
Mike McQuaid committed
91

92
### `deps` [*`options`*] [*`formula`*]
Mike McQuaid's avatar
Mike McQuaid committed
93

94
95
96
Show dependencies for *`formula`*. Additional options specific to *`formula`* may be
appended to the command. When given multiple formula arguments, show the
intersection of dependencies for each formula.
Mike McQuaid's avatar
Mike McQuaid committed
97
98

* `-n`:
99
  Sort dependencies in topological order.
100
101
* `--1`:
  Only show dependencies one level down, instead of recursing.
Mike McQuaid's avatar
Mike McQuaid committed
102
* `--union`:
103
  Show the union of dependencies for multiple *`formula`*, instead of the intersection.
Mike McQuaid's avatar
Mike McQuaid committed
104
105
106
* `--full-name`:
  List dependencies by their full name.
* `--include-build`:
107
  Include `:build` dependencies for *`formula`*.
Mike McQuaid's avatar
Mike McQuaid committed
108
* `--include-optional`:
109
  Include `:optional` dependencies for *`formula`*.
Mike McQuaid's avatar
Mike McQuaid committed
110
* `--include-test`:
111
  Include `:test` dependencies for *`formula`* (non-recursive).
Mike McQuaid's avatar
Mike McQuaid committed
112
* `--skip-recommended`:
113
  Skip `:recommended` dependencies for *`formula`*.
Mike McQuaid's avatar
Mike McQuaid committed
114
115
116
* `--include-requirements`:
  Include requirements in addition to dependencies for *`formula`*.
* `--tree`:
117
  Show dependencies as a tree. When given multiple formula arguments, show individual trees for each formula.
118
119
* `--annotate`:
  Mark any build, test, optional, or recommended dependencies as such in the output.
120
121
122
123
* `--installed`:
  List dependencies for formulae that are currently installed. If *`formula`* is specified, list only its dependencies that are currently installed.
* `--all`:
  List dependencies for all available formulae.
Mike McQuaid's avatar
Mike McQuaid committed
124
* `--for-each`:
125
  Switch into the mode used by the `--all` option, but only list dependencies for each provided *`formula`*, one formula per line. This is used for debugging the `--installed`/`--all` display mode.
Mike McQuaid's avatar
Mike McQuaid committed
126
127
128

### `desc` [*`options`*] (*`text`*|`/`*`text`*`/`|*`formula`*)

129
130
131
Display *`formula`*'s name and one-line description. Formula descriptions are
cached; the cache is created on the first search, making that search slower than
subsequent ones.
Mike McQuaid's avatar
Mike McQuaid committed
132
133

* `-s`, `--search`:
134
  Search both names and descriptions for *`text`*. If *`text`* is flanked by slashes, it is interpreted as a regular expression.
Mike McQuaid's avatar
Mike McQuaid committed
135
* `-n`, `--name`:
136
  Search just names for *`text`*. If *`text`* is flanked by slashes, it is interpreted as a regular expression.
Mike McQuaid's avatar
Mike McQuaid committed
137
* `-d`, `--description`:
138
  Search just descriptions for *`text`*. If *`text`* is flanked by slashes, it is interpreted as a regular expression.
Mike McQuaid's avatar
Mike McQuaid committed
139
140
141

### `diy` [*`options`*]

142
143
144
Automatically determine the installation prefix for non-Homebrew software. Using
the output from this command, you can install your own software into the Cellar
and then link it into Homebrew's prefix with `brew link`.
Mike McQuaid's avatar
Mike McQuaid committed
145
146

* `--name`:
147
  Explicitly set the *`name`* of the package being installed.
Mike McQuaid's avatar
Mike McQuaid committed
148
* `--version`:
149
  Explicitly set the *`version`* of the package being installed.
150

Mike McQuaid's avatar
Mike McQuaid committed
151
### `doctor` [*`options`*]
152

153
Check your system for potential problems. Will exit with a non-zero status if
154
155
156
157
any potential problems are found. Please note that these warnings are just used
to help the Homebrew maintainers with debugging if you file an issue. If
everything you use Homebrew for is working fine: please don't worry or file an
issue; just ignore this.
158

Mike McQuaid's avatar
Mike McQuaid committed
159
* `--list-checks`:
160
  List all audit methods, which can be run individually if provided as arguments.
Mike McQuaid's avatar
Mike McQuaid committed
161
162
* `-D`, `--audit-debug`:
  Enable debugging and profiling of audit methods.
163

Mike McQuaid's avatar
Mike McQuaid committed
164
### `fetch` [*`options`*] *`formula`*
165

166
167
Download a bottle (if available) or source packages for *`formula`*. For tarballs,
also print SHA-256 checksums.
168

Mike McQuaid's avatar
Mike McQuaid committed
169
170
171
172
* `--HEAD`:
  Fetch HEAD version instead of stable version.
* `--devel`:
  Fetch development version instead of stable version.
173
174
175
176
* `-f`, `--force`:
  Remove a previously cached version and re-fetch.
* `-v`, `--verbose`:
  Do a verbose VCS checkout, if the URL represents a VCS. This is useful for seeing if an existing VCS cache has been updated.
Mike McQuaid's avatar
Mike McQuaid committed
177
* `--retry`:
178
  Retry if downloading fails or re-download if the checksum of a previously cached version no longer matches.
Mike McQuaid's avatar
Mike McQuaid committed
179
* `--deps`:
180
  Also download dependencies for any listed *`formula`*.
Mike McQuaid's avatar
Mike McQuaid committed
181
* `-s`, `--build-from-source`:
182
  Download source packages rather than a bottle.
Mike McQuaid's avatar
Mike McQuaid committed
183
* `--build-bottle`:
184
  Download source packages (for eventual bottling) rather than a bottle.
Mike McQuaid's avatar
Mike McQuaid committed
185
186
187
188
189
* `--force-bottle`:
  Download a bottle if it exists for the current or newest version of macOS, even if it would not be used during installation.

### `gist-logs` [*`options`*] *`formula`*

190
191
Upload logs for a failed build of *`formula`* to a new Gist. Presents an error
message if no logs are found.
Mike McQuaid's avatar
Mike McQuaid committed
192
193
194
195

* `--with-hostname`:
  Include the hostname in the Gist.
* `-n`, `--new-issue`:
196
  Automatically create a new issue in the appropriate GitHub repository after creating the Gist.
Mike McQuaid's avatar
Mike McQuaid committed
197
* `-p`, `--private`:
198
  The Gist will be marked private and will not appear in listings but will be accessible with its link.
Mike McQuaid's avatar
Mike McQuaid committed
199
200
201

### `home` [*`formula`*]

202
203
Open *`formula`*'s homepage in a browser, or open Homebrew's own homepage if no
formula is provided.
Mike McQuaid's avatar
Mike McQuaid committed
204

EricFromCanada's avatar
EricFromCanada committed
205
### `info` [*`options`*] [*`formula`*]
Mike McQuaid's avatar
Mike McQuaid committed
206
207
208

Display brief statistics for your Homebrew installation.

209
If *`formula`* is provided, show summary of information about *`formula`*.
EricFromCanada's avatar
EricFromCanada committed
210

Mike McQuaid's avatar
Mike McQuaid committed
211
* `--analytics`:
212
  List global Homebrew analytics data or, if specified, installation and build error data for *`formula`* (provided neither `HOMEBREW_NO_ANALYTICS` nor `HOMEBREW_NO_GITHUB_API` are set).
Mike McQuaid's avatar
Mike McQuaid committed
213
* `--days`:
214
  How many days of analytics data to retrieve. The value for *`days`* must be `30`, `90` or `365`. The default is `30`.
Mike McQuaid's avatar
Mike McQuaid committed
215
* `--category`:
216
  Which type of analytics data to retrieve. The value for *`category`* must be `install`, `install-on-request` or `build-error`; `cask-install` or `os-version` may be specified if *`formula`* is not. The default is `install`.
Mike McQuaid's avatar
Mike McQuaid committed
217
* `--github`:
218
  Open the GitHub source page for *`formula`* in a browser. To view formula history locally: `brew log -p` *`formula`*
Mike McQuaid's avatar
Mike McQuaid committed
219
220
221
* `--json`:
  Print a JSON representation of *`formula`*. Currently the default and only accepted value for *`version`* is `v1`. See the docs for examples of using the JSON output: <https://docs.brew.sh/Querying-Brew>
* `--installed`:
EricFromCanada's avatar
EricFromCanada committed
222
223
224
  Print JSON of formulae that are currently installed.
* `--all`:
  Print JSON of all available formulae.
225
226
* `-v`, `--verbose`:
  Show more verbose analytics data for *`formula`*.
Mike McQuaid's avatar
Mike McQuaid committed
227
228
229

### `install` [*`options`*] *`formula`*

230
231
Install *`formula`*. Additional options specific to *`formula`* may be appended to
the command.
Mike McQuaid's avatar
Mike McQuaid committed
232

233
234
Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
the installed formulae or, every 30 days, for all formulae.
235

236
237
* `-d`, `--debug`:
  If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory.
Mike McQuaid's avatar
Mike McQuaid committed
238
* `--env`:
239
  If `std` is passed, use the standard build environment instead of superenv. If `super` is passed, use superenv even if the formula specifies the standard build environment.
Mike McQuaid's avatar
Mike McQuaid committed
240
* `--ignore-dependencies`:
241
  An unsupported Homebrew development flag to skip installing any dependencies of any kind. If the dependencies are not already present, the formula will have issues. If you're not developing Homebrew, consider adjusting your PATH rather than using this flag.
Mike McQuaid's avatar
Mike McQuaid committed
242
* `--only-dependencies`:
243
  Install the dependencies with specified options but do not install the formula itself.
Mike McQuaid's avatar
Mike McQuaid committed
244
* `--cc`:
245
  Attempt to compile using the specified *`compiler`*, which should be the name of the compiler's executable, e.g. `gcc-7` for GCC 7. In order to use LLVM's clang, specify `llvm_clang`. To use the Apple-provided clang, specify `clang`. This option will only accept compilers that are provided by Homebrew or bundled with macOS. Please do not file issues if you encounter errors while using this option.
Mike McQuaid's avatar
Mike McQuaid committed
246
* `-s`, `--build-from-source`:
247
  Compile *`formula`* from source even if a bottle is provided. Dependencies will still be installed from bottles if they are available.
Mike McQuaid's avatar
Mike McQuaid committed
248
249
250
* `--force-bottle`:
  Install from a bottle if it exists for the current or newest version of macOS, even if it would not normally be used for installation.
* `--include-test`:
251
  Install testing dependencies required to run `brew test` *`formula`*.
Mike McQuaid's avatar
Mike McQuaid committed
252
253
254
255
256
* `--devel`:
  If *`formula`* defines it, install the development version.
* `--HEAD`:
  If *`formula`* defines it, install the HEAD version, aka. master, trunk, unstable.
* `--fetch-HEAD`:
257
  Fetch the upstream repository to detect if the HEAD installation of the formula is outdated. Otherwise, the repository's HEAD will only be checked for updates when a new stable or development version has been released.
Mike McQuaid's avatar
Mike McQuaid committed
258
* `--keep-tmp`:
259
  Retain the temporary files created during installation.
Mike McQuaid's avatar
Mike McQuaid committed
260
* `--build-bottle`:
261
  Prepare the formula for eventual bottling during installation, skipping any post-install steps.
Mike McQuaid's avatar
Mike McQuaid committed
262
* `--bottle-arch`:
263
  Optimise bottles for the specified architecture rather than the oldest architecture supported by the version of macOS the bottles are built on.
264
265
266
267
* `-f`, `--force`:
  Install without checking for previously installed keg-only or non-migrated versions.
* `-v`, `--verbose`:
  Print the verification and postinstall steps.
Mike McQuaid's avatar
Mike McQuaid committed
268
269
270
271
272
273
* `--display-times`:
  Print install times for each formula at the end of the run.
* `-i`, `--interactive`:
  Download and patch *`formula`*, then open a shell. This allows the user to run `./configure --help` and otherwise determine how to turn the software package into a Homebrew package.
* `-g`, `--git`:
  Create a Git repository, useful for creating patches to the software.
274

Mike McQuaid's avatar
Mike McQuaid committed
275
### `leaves`
276

277
List installed formulae that are not dependencies of another installed formula.
278

279
### `link`, `ln` [*`options`*] *`formula`*
280

281
282
Symlink all of *`formula`*'s installed files into Homebrew's prefix. This is done
automatically when you install formulae but can be useful for DIY installations.
283

Mike McQuaid's avatar
Mike McQuaid committed
284
* `--overwrite`:
285
  Delete files that already exist in the prefix while linking.
Mike McQuaid's avatar
Mike McQuaid committed
286
* `-n`, `--dry-run`:
287
  List files which would be linked or deleted by `brew link --overwrite` without actually linking or deleting any files.
288
289
* `-f`, `--force`:
  Allow keg-only formulae to be linked.
290

291
### `list`, `ls` [*`options`*] [*`formula`*]
292

Mike McQuaid's avatar
Mike McQuaid committed
293
List all installed formulae.
294

295
If *`formula`* is provided, summarise the paths within its current keg.
296

Mike McQuaid's avatar
Mike McQuaid committed
297
* `--full-name`:
298
  Print formulae with fully-qualified names. If `--full-name` is not passed, other options (i.e. `-1`, `-l`, `-r` and `-t`) are passed to `ls`(1) which produces the actual output.
Mike McQuaid's avatar
Mike McQuaid committed
299
* `--unbrewed`:
300
  List files in Homebrew's prefix not installed by Homebrew.
Mike McQuaid's avatar
Mike McQuaid committed
301
* `--versions`:
302
  Show the version number for installed formulae, or only the specified formulae if *`formula`* are provided.
Mike McQuaid's avatar
Mike McQuaid committed
303
304
305
* `--multiple`:
  Only show formulae with multiple versions installed.
* `--pinned`:
306
  Show the versions of pinned formulae, or only the specified (pinned) formulae if *`formula`* are provided. See also `pin`, `unpin`.
Mike McQuaid's avatar
Mike McQuaid committed
307
308
309
* `-1`:
  Force output to be one entry per line. This is the default when output is not to a terminal.
* `-l`:
310
  List in long format. If the output is to a terminal, a total sum for all the file sizes is printed before the long listing.
Mike McQuaid's avatar
Mike McQuaid committed
311
* `-r`:
312
  Reverse the order of the sort to list the oldest entries first.
Mike McQuaid's avatar
Mike McQuaid committed
313
* `-t`:
314
  Sort by time modified, listing most recently modified first.
315

316
### `log` [*`options`*] [*`formula`*]
317

318
319
Show the `git log` for *`formula`*, or show the log for the Homebrew repository if
no formula is provided.
320

Mike McQuaid's avatar
Mike McQuaid committed
321
* `-p`, `--patch`:
322
  Also print patch from commit.
Mike McQuaid's avatar
Mike McQuaid committed
323
* `--stat`:
324
  Also print diffstat from commit.
Mike McQuaid's avatar
Mike McQuaid committed
325
* `--oneline`:
326
  Print only one line per commit.
Mike McQuaid's avatar
Mike McQuaid committed
327
* `-1`, `--max-count`:
328
  Print only one or a specified number of commits.
329

Mike McQuaid's avatar
Mike McQuaid committed
330
### `migrate` [*`options`*] *`formula`*
331

332
333
Migrate renamed packages to new names, where *`formula`* are old names of
packages.
334

335
336
337
* `-f`, `--force`:
  Treat installed *`formula`* and provided *`formula`* as if they are from the same taps and migrate them anyway.

338
### `missing` [*`options`*] [*`formula`*]
339

340
341
342
Check the given *`formula`* kegs for missing dependencies. If no *`formula`* are
provided, check all kegs. Will exit with a non-zero status if any kegs are found
to be missing dependencies.
343

Mike McQuaid's avatar
Mike McQuaid committed
344
* `--hide`:
345
  Act as if none of the specified *`hidden`* are installed. *`hidden`* should be a comma-separated list of formulae.
346

347
### `options` [*`options`*] [*`formula`*]
348

349
Show install options specific to *`formula`*.
350

Mike McQuaid's avatar
Mike McQuaid committed
351
352
353
* `--compact`:
  Show all options on a single line separated by spaces.
* `--installed`:
354
355
356
  Show options for formulae that are currently installed.
* `--all`:
  Show options for all available formulae.
357

358
### `outdated` [*`options`*] [*`formula`*]
359

360
361
362
List installed formulae that have an updated version available. By default,
version information is displayed in interactive shells, and suppressed
otherwise.
363

364
365
366
367
* `-q`, `--quiet`:
  List only the names of outdated kegs (takes precedence over `--verbose`).
* `-v`, `--verbose`:
  Include detailed version information.
Mike McQuaid's avatar
Mike McQuaid committed
368
* `--json`:
369
  Print output in JSON format. Currently the default and only accepted value for *`version`* is `v1`. See the docs for examples of using the JSON output: <https://docs.brew.sh/Querying-Brew>
Mike McQuaid's avatar
Mike McQuaid committed
370
* `--fetch-HEAD`:
371
  Fetch the upstream repository to detect if the HEAD installation of the formula is outdated. Otherwise, the repository's HEAD will only be checked for updates when a new stable or development version has been released.
372

Mike McQuaid's avatar
Mike McQuaid committed
373
### `pin` *`formula`*
374

375
376
Pin the specified *`formula`*, preventing them from being upgraded when issuing
the `brew upgrade` *`formula`* command. See also `unpin`.
377

Mike McQuaid's avatar
Mike McQuaid committed
378
### `postinstall` *`formula`*
379

Mike McQuaid's avatar
Mike McQuaid committed
380
Rerun the post-install steps for *`formula`*.
381

Mike McQuaid's avatar
Mike McQuaid committed
382
### `readall` [*`options`*] [*`tap`*]
383

384
385
386
Import all formulae from the specified *`tap`*, or from all installed taps if none
is provided. This can be useful for debugging issues across all formulae when
making significant changes to `formula.rb`, testing the performance of loading
387
all formulae or checking if any current formulae have Ruby issues.
388

Mike McQuaid's avatar
Mike McQuaid committed
389
390
391
392
* `--aliases`:
  Verify any alias symlinks in each tap.
* `--syntax`:
  Syntax-check all of Homebrew's Ruby files.
393

Mike McQuaid's avatar
Mike McQuaid committed
394
### `reinstall` [*`options`*] *`formula`*
395

396
397
Uninstall and then install *`formula`* using the same options it was originally
installed with, plus any appended brew formula options.
398

399
400
Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
the reinstalled formulae or, every 30 days, for all formulae.
401

402
403
* `-d`, `--debug`:
  If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory.
Mike McQuaid's avatar
Mike McQuaid committed
404
405
406
407
408
* `-s`, `--build-from-source`:
  Compile *`formula`* from source even if a bottle is available.
* `--force-bottle`:
  Install from a bottle if it exists for the current or newest version of macOS, even if it would not normally be used for installation.
* `--keep-tmp`:
409
  Retain the temporary files created during installation.
410
411
412
413
* `-f`, `--force`:
  Install without checking for previously installed keg-only or non-migrated versions.
* `-v`, `--verbose`:
  Print the verification and postinstall steps.
Mike McQuaid's avatar
Mike McQuaid committed
414
415
* `--display-times`:
  Print install times for each formula at the end of the run.
416

Mike McQuaid's avatar
Mike McQuaid committed
417
### `search` [*`options`*] [*`text`*|`/`*`text`*`/`]
418

419
Perform a substring search of cask tokens and formula names for *`text`*. If
420
421
*`text`* is flanked by slashes, it is interpreted as a regular expression. The
search for *`text`* is extended online to `homebrew/core` and `homebrew/cask`.
422

423
If no *`text`* is provided, list all locally available formulae (including tapped
424
ones). No online search is performed.
425

Mike McQuaid's avatar
Mike McQuaid committed
426
* `--casks`:
427
  List all locally available casks (including tapped ones). No online search is performed.
Mike McQuaid's avatar
Mike McQuaid committed
428
* `--desc`:
429
  Search for formulae with a description matching *`text`* and casks with a name matching *`text`*.
Mike McQuaid's avatar
Mike McQuaid committed
430
431
432
433
434
435
436
437
438
439
440
441
* `--macports`:
  Search for *`text`* in the given package manager's list.
* `--fink`:
  Search for *`text`* in the given package manager's list.
* `--opensuse`:
  Search for *`text`* in the given package manager's list.
* `--fedora`:
  Search for *`text`* in the given package manager's list.
* `--debian`:
  Search for *`text`* in the given package manager's list.
* `--ubuntu`:
  Search for *`text`* in the given package manager's list.
442

Mike McQuaid's avatar
Mike McQuaid committed
443
### `sh` [*`options`*]
444

Mike McQuaid's avatar
Mike McQuaid committed
445
Start a Homebrew build environment shell. Uses our years-battle-hardened
446
447
448
Homebrew build logic to help your `./configure && make && make install` or even
your `gem install` succeed. Especially handy if you run Homebrew in an
Xcode-only configuration since it adds tools like `make` to your `PATH` which
449
build systems would not find otherwise.
450

Mike McQuaid's avatar
Mike McQuaid committed
451
* `--env`:
452
  Use the standard `PATH` instead of superenv's when `std` is passed.
453

Mike McQuaid's avatar
Mike McQuaid committed
454
### `shellenv`
455

456
Print export statements. When run in a shell, this installation of Homebrew will be added to your `PATH`, `MANPATH`, and `INFOPATH`.
457

458
The variables `HOMEBREW_PREFIX`, `HOMEBREW_CELLAR` and `HOMEBREW_REPOSITORY` are also exported to avoid querying them multiple times.
459
Consider adding evaluation of this command's output to your dotfiles (e.g. `~/.profile` or `~/.zprofile`) with: `eval $(brew shellenv)`
460

Mike McQuaid's avatar
Mike McQuaid committed
461
### `style` [*`options`*] [*`file`*|*`tap`*|*`formula`*]
462

Mike McQuaid's avatar
Mike McQuaid committed
463
Check formulae or files for conformance to Homebrew style guidelines.
464

465
466
467
Lists of *`file`*, *`tap`* and *`formula`* may not be combined. If none are provided,
`style` will run style checks on the whole Homebrew library, including core code
and all formulae.
468

Mike McQuaid's avatar
Mike McQuaid committed
469
470
471
472
473
474
475
476
* `--fix`:
  Fix style violations automatically using RuboCop's auto-correct feature.
* `--display-cop-names`:
  Include the RuboCop cop name for each violation in the output.
* `--only-cops`:
  Specify a comma-separated *`cops`* list to check for violations of only the listed RuboCop cops.
* `--except-cops`:
  Specify a comma-separated *`cops`* list to skip checking for violations of the listed RuboCop cops.
477

Mike McQuaid's avatar
Mike McQuaid committed
478
### `switch` *`formula`* *`version`*
479

480
481
Symlink all of the specified *`version`* of *`formula`*'s installation into
Homebrew's prefix.
482

Mike McQuaid's avatar
Mike McQuaid committed
483
### `tap` [*`options`*] *`user`*`/`*`repo`* [*`URL`*]
484

Mike McQuaid's avatar
Mike McQuaid committed
485
Tap a formula repository.
486

487
If no arguments are provided, list all installed taps.
488

489
With *`URL`* unspecified, tap a formula repository from GitHub using HTTPS. Since
490
491
so many taps are hosted on GitHub, this command is a shortcut for `brew tap`
*`user`*`/`*`repo`* `https://github.com/`*`user`*`/homebrew-`*`repo`*.
492

493
494
495
496
497
With *`URL`* specified, tap a formula repository from anywhere, using any
transport protocol that `git`(1) handles. The one-argument form of `tap`
simplifies but also limits. This two-argument command makes no assumptions, so
taps can be cloned from places other than GitHub and using protocols other than
HTTPS, e.g. SSH, GIT, HTTP, FTP(S), RSYNC.
498

Mike McQuaid's avatar
Mike McQuaid committed
499
* `--full`:
500
  Use a full clone when tapping a repository. By default, the repository is cloned as a shallow copy (`--depth=1`). To convert a shallow copy to a full copy, you can retap by passing `--full` without first untapping.
Mike McQuaid's avatar
Mike McQuaid committed
501
502
503
504
505
506
507
508
* `--force-auto-update`:
  Auto-update tap even if it is not hosted on GitHub. By default, only taps hosted on GitHub are auto-updated (for performance reasons).
* `--repair`:
  Migrate tapped formulae from symlink-based to directory-based structure.
* `--list-pinned`:
  List all pinned taps.
* `-q`, `--quieter`:
  Suppress any warnings.
509

Mike McQuaid's avatar
Mike McQuaid committed
510
### `tap-info` [*`options`*] [*`tap`*]
511

512
513
514
Show detailed information about one or more *`tap`*s.

If no *`tap`* names are provided, display brief statistics for all installed taps.
515

Mike McQuaid's avatar
Mike McQuaid committed
516
* `--installed`:
517
  Show information on each installed tap.
Mike McQuaid's avatar
Mike McQuaid committed
518
* `--json`:
519
  Print a JSON representation of *`tap`*. Currently the default and only accepted value for *`version`* is `v1`. See the docs for examples of using the JSON output: <https://docs.brew.sh/Querying-Brew>
520

Mike McQuaid's avatar
Mike McQuaid committed
521
### `uninstall`, `rm`, `remove` [*`options`*] *`formula`*
522

Mike McQuaid's avatar
Mike McQuaid committed
523
Uninstall *`formula`*.
524

525
526
* `-f`, `--force`:
  Delete all installed versions of *`formula`*.
Mike McQuaid's avatar
Mike McQuaid committed
527
528
* `--ignore-dependencies`:
  Don't fail uninstall, even if *`formula`* is a dependency of any installed formulae.
529

Mike McQuaid's avatar
Mike McQuaid committed
530
### `unlink` [*`options`*] *`formula`*
531

532
Remove symlinks for *`formula`* from Homebrew's prefix. This can be useful for
533
534
temporarily disabling a formula: `brew unlink` *`formula`* `&&` *`commands`* `&&
brew link` *`formula`*
535

Mike McQuaid's avatar
Mike McQuaid committed
536
* `-n`, `--dry-run`:
537
  List files which would be unlinked without actually unlinking or deleting any files.
538

Mike McQuaid's avatar
Mike McQuaid committed
539
### `unpack` [*`options`*] *`formula`*
540

541
542
Unpack the source files for *`formula`* into subdirectories of the current working
directory.
543

Mike McQuaid's avatar
Mike McQuaid committed
544
545
546
547
548
549
* `--destdir`:
  Create subdirectories in the directory named by *`path`* instead.
* `--patch`:
  Patches for *`formula`* will be applied to the unpacked source.
* `-g`, `--git`:
  Initialise a Git repository in the unpacked source. This is useful for creating patches for the software.
550

Mike McQuaid's avatar
Mike McQuaid committed
551
### `unpin` *`formula`*
552

553
554
Unpin *`formula`*, allowing them to be upgraded by `brew upgrade` *`formula`*. See
also `pin`.
555

Mike McQuaid's avatar
Mike McQuaid committed
556
### `untap` *`tap`*
557

558
Remove a tapped formula repository.
559

560
### `update`, `up` [*`options`*]
561

Mike McQuaid's avatar
Mike McQuaid committed
562
Fetch the newest version of Homebrew and all formulae from GitHub using `git`(1) and perform any necessary migrations.
563

Mike McQuaid's avatar
Mike McQuaid committed
564
* `--merge`:
565
  Use `git merge` to apply updates (rather than `git rebase`).
566

Mike McQuaid's avatar
Mike McQuaid committed
567
### `update-reset` [*`repository`*]
568

569
Fetch and reset Homebrew and all tap repositories (or any specified *`repository`*) using `git`(1) to their latest `origin/master`.
570

571
*Note:* this will destroy all your uncommitted or committed changes.
572

573
### `upgrade` [*`options`*] [*`formula`*]
574

575
576
577
578
Upgrade outdated, unpinned formulae using the same options they were originally
installed with, plus any appended brew formula options. If *`formula`* are
specified, upgrade only the given *`formula`* kegs (unless they are pinned; see
`pin`, `unpin`).
579

580
581
Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
the upgraded formulae or, every 30 days, for all formulae.
582

583
584
* `-d`, `--debug`:
  If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory.
Mike McQuaid's avatar
Mike McQuaid committed
585
586
587
588
589
* `-s`, `--build-from-source`:
  Compile *`formula`* from source even if a bottle is available.
* `--force-bottle`:
  Install from a bottle if it exists for the current or newest version of macOS, even if it would not normally be used for installation.
* `--fetch-HEAD`:
590
  Fetch the upstream repository to detect if the HEAD installation of the formula is outdated. Otherwise, the repository's HEAD will only be checked for updates when a new stable or development version has been released.
Mike McQuaid's avatar
Mike McQuaid committed
591
* `--ignore-pinned`:
592
  Set a successful exit status even if pinned formulae are not upgraded.
Mike McQuaid's avatar
Mike McQuaid committed
593
* `--keep-tmp`:
594
  Retain the temporary files created during installation.
595
596
597
598
* `-f`, `--force`:
  Install without checking for previously installed keg-only or non-migrated versions.
* `-v`, `--verbose`:
  Print the verification and postinstall steps.
Mike McQuaid's avatar
Mike McQuaid committed
599
600
* `--display-times`:
  Print install times for each formula at the end of the run.
601
* `-n`, `--dry-run`:
602
  Show what would be upgraded, but do not actually upgrade anything.
Mike McQuaid's avatar
Mike McQuaid committed
603
604
605

### `uses` [*`options`*] *`formula`*

606
607
608
609
Show formulae that specify *`formula`* as a dependency. When given multiple
formula arguments, show the intersection of formulae that use *`formula`*. By
default, `uses` shows all formulae that specify *`formula`* as a required or
recommended dependency for their stable builds.
Mike McQuaid's avatar
Mike McQuaid committed
610
611
612
613

* `--recursive`:
  Resolve more than one level of dependencies.
* `--installed`:
614
  Only list formulae that are currently installed.
Mike McQuaid's avatar
Mike McQuaid committed
615
616
617
618
619
620
621
622
623
* `--include-build`:
  Include all formulae that specify *`formula`* as `:build` type dependency.
* `--include-test`:
  Include all formulae that specify *`formula`* as `:test` type dependency.
* `--include-optional`:
  Include all formulae that specify *`formula`* as `:optional` type dependency.
* `--skip-recommended`:
  Skip all formulae that specify *`formula`* as `:recommended` type dependency.
* `--devel`:
624
  Show usage of *`formula`* by development builds.
Mike McQuaid's avatar
Mike McQuaid committed
625
* `--HEAD`:
626
  Show usage of *`formula`* by HEAD builds.
627

Mike McQuaid's avatar
Mike McQuaid committed
628
### `--cache` [*`options`*] [*`formula`*]
629

Mike McQuaid's avatar
Mike McQuaid committed
630
Display Homebrew's download cache. See also `HOMEBREW_CACHE`.
631

Mike McQuaid's avatar
Mike McQuaid committed
632
If *`formula`* is provided, display the file or directory used to cache *`formula`*.
633

Mike McQuaid's avatar
Mike McQuaid committed
634
635
636
637
* `-s`, `--build-from-source`:
  Show the cache file used when building from source.
* `--force-bottle`:
  Show the cache file used when pouring a bottle.
638

639
### `--cellar` [*`formula`*]
640

641
642
Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if that
directory doesn't exist, `$(brew --repository)/Cellar`.
643

Mike McQuaid's avatar
Mike McQuaid committed
644
645
If *`formula`* is provided, display the location in the cellar where *`formula`*
would be installed, without any sort of versioned directory as the last path.
646

647
### `--env` [*`options`*] [*`formula`*]
Gautham Goli's avatar
Gautham Goli committed
648

649
Summarise Homebrew's build environment as a plain list.
Gautham Goli's avatar
Gautham Goli committed
650

651
652
If the command's output is sent through a pipe and no shell is specified, the
list is formatted for export to `bash`(1) unless `--plain` is passed.
Gautham Goli's avatar
Gautham Goli committed
653

Mike McQuaid's avatar
Mike McQuaid committed
654
655
656
* `--shell`:
  Generate a list of environment variables for the specified shell, or `--shell=auto` to detect the current shell.
* `--plain`:
657
  Generate plain output even when piped.
658

Mike McQuaid's avatar
Mike McQuaid committed
659
### `--prefix` [*`formula`*]
660

Mike McQuaid's avatar
Mike McQuaid committed
661
662
Display Homebrew's install path. *Default:* `/usr/local` on macOS and
`/home/linuxbrew/.linuxbrew` on Linux.
663

664
665
If *`formula`* is provided, display the location in the cellar where *`formula`* is
or would be installed.
666

667
### `--repository`, `--repo` [*`user`*`/`*`repo`*]
668

Mike McQuaid's avatar
Mike McQuaid committed
669
Display where Homebrew's `.git` directory is located.
670

671
672
If *`user`*`/`*`repo`* are provided, display where tap *`user`*`/`*`repo`*'s directory
is located.
673

Mike McQuaid's avatar
Mike McQuaid committed
674
### `--version`
675

676
677
Print the version numbers of Homebrew, Homebrew/homebrew-core and
Homebrew/homebrew-cask (if tapped) to standard output.
678
679
680

## DEVELOPER COMMANDS

681
### `audit` [*`options`*] [*`formula`*]
Gautham Goli's avatar
Gautham Goli committed
682

Mike McQuaid's avatar
Mike McQuaid committed
683
Check *`formula`* for Homebrew coding style violations. This should be run before
684
685
686
submitting a new formula. If no *`formula`* are provided, check all locally
available formulae. Will exit with a non-zero status if any errors are found,
which can be useful for implementing pre-commit hooks.
Gautham Goli's avatar
Gautham Goli committed
687

688
689
690
691
692
693
694
695
696
697
698
* `--strict`:
  Run additional style checks, including RuboCop style checks.
* `--online`:
  Run additional slower style checks that require a network connection.
* `--new-formula`:
  Run various additional style checks to determine if a new formula is eligible for Homebrew. This should be used when creating new formula and implies `--strict` and `--online`.
* `--fix`:
  Fix style violations automatically using RuboCop's auto-correct feature.
* `--display-cop-names`:
  Include the RuboCop cop name for each violation in the output.
* `--display-filename`:
699
  Prefix every line of output with the file or formula name being audited, to make output easy to grep.
700
701
702
703
704
705
706
707
708
709
710
* `-D`, `--audit-debug`:
  Enable debugging and profiling of audit methods.
* `--only`:
  Specify a comma-separated *`method`* list to only run the methods named `audit_`*`method`*.
* `--except`:
  Specify a comma-separated *`method`* list to skip running the methods named `audit_`*`method`*.
* `--only-cops`:
  Specify a comma-separated *`cops`* list to check for violations of only the listed RuboCop cops.
* `--except-cops`:
  Specify a comma-separated *`cops`* list to skip checking for violations of the listed RuboCop cops.

Mike McQuaid's avatar
Mike McQuaid committed
711
### `bottle` [*`options`*] *`formula`*
712
713

Generate a bottle (binary package) from a formula that was installed with
714
715
716
`--build-bottle`. If the formula specifies a rebuild version, it will be
incremented in the generated DSL. Passing `--keep-old` will attempt to keep it
at its original value, while `--no-rebuild` will remove it.
717
718
719
720

* `--skip-relocation`:
  Do not check if the bottle can be marked as relocatable.
* `--force-core-tap`:
721
  Build a bottle even if *`formula`* is not in `homebrew/core` or any installed taps.
722
723
724
725
726
* `--no-rebuild`:
  If the formula specifies a rebuild version, remove it from the generated DSL.
* `--keep-old`:
  If the formula specifies a rebuild version, attempt to preserve its value in the generated DSL.
* `--json`:
727
  Write bottle information to a JSON file, which can be used as the value for `--merge`.
728
* `--merge`:
729
  Generate an updated bottle block for a formula and optionally merge it into the formula file. Instead of a formula name, requires the path to a JSON file generated with `brew bottle --json` *`formula`*.
730
* `--write`:
731
  Write changes to the formula file. A new commit will be generated unless `--no-commit` is passed.
732
733
734
735
736
737
738
* `--no-commit`:
  When passed with `--write`, a new commit will not generated after writing changes to the formula file.
* `--root-url`:
  Use the specified *`URL`* as the root of the bottle's URL instead of Homebrew's default.

### `bump-formula-pr` [*`options`*] [*`formula`*]

739
Create a pull request to update *`formula`* with a new URL or a new tag.
740
741
742
743
744
745
746
747
748
749

If a *`URL`* is specified, the *`SHA-256`* checksum of the new download should also
be specified. A best effort to determine the *`SHA-256`* and *`formula`* name will
be made if either or both values are not supplied by the user.

If a *`tag`* is specified, the Git commit *`revision`* corresponding to that tag
must also be specified.

*Note:* this command cannot be used to transition a formula from a
URL-and-SHA-256 style specification into a tag-and-revision style specification,
750
751
nor vice versa. It must use whichever style specification the formula already
uses.
752
753
754
755
756
757
758

* `--devel`:
  Bump the development rather than stable version. The development spec must already exist.
* `-n`, `--dry-run`:
  Print what would be done rather than doing it.
* `--write`:
  When passed along with `--dry-run`, perform a not-so-dry run by making the expected file modifications but not taking any Git actions.
759
760
* `--no-audit`:
  Don't run `brew audit` before opening the PR.
761
762
763
764
* `--strict`:
  Run `brew audit --strict` before opening the PR.
* `--no-browse`:
  Print the pull request URL instead of opening in a browser.
Maxim Belkin's avatar
Maxim Belkin committed
765
766
* `--no-fork`:
  Don't try to fork the repository.
767
* `--mirror`:
768
  Use the specified *`URL`* as a mirror URL.
769
* `--version`:
770
  Use the specified *`version`* to override the value parsed from the URL or tag. Note that `--version=0` can be used to delete an existing version override from a formula if it has become redundant.
771
* `--message`:
772
  Append *`message`* to the default pull request message.
773
774
775
776
777
778
779
* `--url`:
  Specify the *`URL`* for the new download. If a *`URL`* is specified, the *`SHA-256`* checksum of the new download should also be specified.
* `--sha256`:
  Specify the *`SHA-256`* checksum of the new download.
* `--tag`:
  Specify the new git commit *`tag`* for the formula.
* `--revision`:
780
  Specify the new git commit *`revision`* corresponding to the specified *`tag`*.
781

782
### `bump-revision` [*`options`*] *`formula`*
783

784
785
Create a commit to increment the revision of *`formula`*. If no revision is
present, "revision 1" will be added.
786
787
788
789

* `-n`, `--dry-run`:
  Print what would be done rather than doing it.
* `--message`:
790
  Append *`message`* to the default commit message.
791
792

### `create` [*`options`*] *`URL`*
Gautham Goli's avatar
Gautham Goli committed
793

794
Generate a formula for the downloadable file at *`URL`* and open it in the editor.
795
796
797
798
Homebrew will attempt to automatically derive the formula name and version, but
if it fails, you'll have to make your own template. The `wget` formula serves as
a simple example. For the complete API, see:
<http://www.rubydoc.info/github/Homebrew/brew/master/Formula>
Gautham Goli's avatar
Gautham Goli committed
799

800
801
802
803
* `--autotools`:
  Create a basic template for an Autotools-style build.
* `--cmake`:
  Create a basic template for a CMake-style build.
Dawid Dziurla's avatar
Dawid Dziurla committed
804
805
* `--go`:
  Create a basic template for a Go build.
806
807
* `--meson`:
  Create a basic template for a Meson-style build.
Dawid Dziurla's avatar
Dawid Dziurla committed
808
809
* `--perl`:
  Create a basic template for a Perl build.
Dawid Dziurla's avatar
Dawid Dziurla committed
810
811
* `--python`:
  Create a basic template for a Python build.
Dawid Dziurla's avatar
Dawid Dziurla committed
812
813
* `--rust`:
  Create a basic template for a Rust build.
814
* `--no-fetch`:
815
  Homebrew will not download *`URL`* to the cache and will thus not add its SHA-256 to the formula for you, nor will it check the GitHub API for GitHub projects (to fill out its description and homepage).
816
817
818
* `--HEAD`:
  Indicate that *`URL`* points to the package's repository rather than a file.
* `--set-name`:
819
  Explicitly set the *`name`* of the new formula.
820
* `--set-version`:
821
  Explicitly set the *`version`* of the new formula.
822