brew Shell Completion

Homebrew provides completion definitions for brew in Bash, fish and zsh. Some formulae and external commands provide completions for their own commands.

Homebrew stores completions under HOMEBREW_PREFIX, which a system shell may not search automatically. The installer does not modify every shell's completion configuration because startup files and plugin managers vary.

Completions supplied by external Homebrew commands are not linked automatically. Enable them with:

brew completions link

Bash

Add the following to ~/.bash_profile, or to ~/.profile when ~/.bash_profile does not exist:

if type brew &>/dev/null
then
  HOMEBREW_PREFIX="$(brew --prefix)"
  if [[ -r "${HOMEBREW_PREFIX}/etc/profile.d/bash_completion.sh" ]]
  then
    source "${HOMEBREW_PREFIX}/etc/profile.d/bash_completion.sh"
  else
    for COMPLETION in "${HOMEBREW_PREFIX}/etc/bash_completion.d/"*
    do
      [[ -r "${COMPLETION}" ]] && source "${COMPLETION}"
    done
  fi
fi

The bash-completion formula supports the system Bash shipped by macOS. Use bash-completion@2 with Homebrew's Bash 4 or newer. The two formulae conflict with each other, so install only one. The snippet above loads the installed version, so do not also source it elsewhere in the same shell configuration.

zsh

brew shellenv adds Homebrew's zsh completion directory to FPATH. Ensure that eval "$(brew shellenv)" runs before zsh initialises completion, then add the following to ~/.zshrc if your configuration or framework does not already call compinit:

autoload -Uz compinit
compinit

Oh My Zsh calls compinit when it loads. Make sure brew shellenv is evaluated first, particularly on Linux.

If zsh reports insecure completion directories, run compaudit to list the affected paths. Inspect their ownership and remove group or world write access only from the directories reported by compaudit. Do not recursively change permissions across the entire Homebrew prefix.

fish

Homebrew's fish formula discovers Homebrew-managed completions automatically.

For a fish installation from another source, add the following to ~/.config/fish/config.fish:

if test -d (brew --prefix)"/share/fish/completions"
    set -p fish_complete_path (brew --prefix)/share/fish/completions
end

if test -d (brew --prefix)"/share/fish/vendor_completions.d"
    set -p fish_complete_path (brew --prefix)/share/fish/vendor_completions.d
end

PowerShell

Some formulae install PowerShell completions for their own commands under Homebrew's PowerShell completion directory. Homebrew does not currently provide a PowerShell completion definition for brew itself.

Add the following to your PowerShell profile, such as ~/.config/powershell/Microsoft.PowerShell_profile.ps1:

if ((Get-Command brew -ErrorAction SilentlyContinue) -and (Test-Path ($completions = "$(brew --prefix)/share/pwsh/completions"))) {
  foreach ($f in Get-ChildItem -Path $completions -File) {
    . $f
  }
}