Skip to main content

✨ Completion Configuration

Initialize completion​

Zsh's modern completion system is initialized by compinit. Load it once, after adding all required completion directories to fpath:

~/.zshrc
autoload -Uz compinit
compinit

See the Completion System manual for initialization options and security checks.

Configure completion with zstyle​

The completion system reads zstyle values from contexts such as :completion:*. A more specific context overrides a broader one, which lets you tune individual completers, commands, or tags.

Approximate matching​

~/.zshrc
zstyle ':completion:*' completer _complete _match _approximate
zstyle ':completion:*:match:*' original only
zstyle -e ':completion:*:approximate:*' max-errors \
  'reply=($((($#PREFIX + $#SUFFIX) / 3 > 7 ? 7 : ($#PREFIX + $#SUFFIX) / 3))numeric)'

Grouping, descriptions, and matching​

~/.zshrc
zstyle ':completion:*:matches' group yes
zstyle ':completion:*:options' description yes
zstyle ':completion:*:options' auto-description '%d'
zstyle ':completion:*:corrections' format ' %F{green}-- %d (errors: %e) --%f'
zstyle ':completion:*:descriptions' format ' %F{yellow}-- %d --%f'
zstyle ':completion:*:messages' format ' %F{purple}-- %d --%f'
zstyle ':completion:*:warnings' format ' %F{red}-- no matches found --%f'
zstyle ':completion:*:default' list-prompt '%S%M matches%s'
zstyle ':completion:*' group-name ''
zstyle ':completion:*' verbose yes
zstyle ':completion:*' matcher-list \
  'm:{a-zA-Z}={A-Za-z}' \
  'r:|[._-]=* r:|=*' \
  'l:|=* r:|=*'
zstyle ':completion:*:functions' ignored-patterns '(_*|pre(cmd|exec))'
zstyle ':completion:*' use-cache true
~/.zshrc
zstyle ':completion:*' menu select

Colors​

When LS_COLORS is defined, split its colon-separated value into the array expected by list-colors:

~/.zshrc
zstyle ':completion:*' list-colors ${(s.:.)LS_COLORS}

Ubuntu's global compinit call​

Ubuntu's system-wide Zsh configuration can call compinit automatically. If your own .zshrc initializes completion, prevent the duplicate call by setting this distro-specific variable in $ZDOTDIR/.zshenv (normally ~/.zshenv):

~/.zshenv
skip_global_compinit=1

This variable is an Ubuntu packaging convention, not a portable Zsh setting. The current behavior is documented in the Debian package source.