---
title: ✨ Completion Configuration
description: Configure Zsh completion behavior and styles with compinit and zstyle.
canonical_url: https://wiki.zshell.dev/community/zsh-guide/completion
markdown_url: https://wiki.zshell.dev/community/zsh-guide/completion/index.md
locale: en
source_path: community/01_zsh_guide/03_completion.mdx
---

<!-- Generated from the canonical Z-Shell Wiki build. The linked human-facing page remains the editorial source of truth. -->

# ✨ Completion Configuration

<a id="initialize-completion"></a>

## Initialize completion

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

~/.zshrc

```zsh
autoload -Uz compinit
compinit
```

See the [Completion System manual](https://zsh.sourceforge.io/Doc/Release/Completion-System.html) for initialization options and security checks.

<a id="configure-completion-with-zstyle"></a>

## 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.

<a id="approximate-matching"></a>

### Approximate matching

~/.zshrc

```zsh
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)'
```

<a id="grouping-descriptions-and-matching"></a>

### Grouping, descriptions, and matching

~/.zshrc

```zsh
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
```

<a id="menu-selection"></a>

### Menu selection

~/.zshrc

```zsh
zstyle ':completion:*' menu select
```

<a id="completion-colors"></a>

### Colors

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

~/.zshrc

```zsh
zstyle ':completion:*' list-colors ${(s.:.)LS_COLORS}
```

<a id="ubuntu-global-compinit"></a>

## 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

```zsh
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](https://sources.debian.org/src/zsh/5.9-8/debian/zshrc/).