zsh completion system: inconsistent behavior across macOS and Linux distributions

Answer

To obtain identical, high‑performance completion on both platforms, ensure the completion directory is added to fpath before calling compinit, invoke compinit with the insecure‑skip flag (or use a dump file), and set a few neutral zstyle options.

Likely explanation

The discrepancy mainly arises because macOS ships with an older default zsh version whose fpath does not include the system‑wide completion directories that most Linux distributions provide. When the same zsh-completions package is loaded, the fpath order differs, causing compinit to scan different sets of directories and triggering macOS’s security‑check prompts or extra loading time.

Confirmed facts

• compinit performs a security check on each directory in fpath; this check can prompt for confirmation on macOS when directories are group‑writable or owned by another user.
• Adding the completion directory ($(brew --prefix)/share/zsh-completions on macOS or /usr/share/zsh/functions/Completion on Linux) to fpath before compinit is required for the package’s functions to be visible.
• Using compinit -i (or -C with a pre‑generated dump) skips the insecure‑check and greatly reduces startup latency.
• Default zstyle settings (e.g., menu selection) vary between distributions, affecting whether completion lists appear as a menu or a simple list.

Minimal configuration steps

1. Determine the completion directory for your platform and prepend it to fpath:

# macOS (Homebrew)
if [[ -d "$(brew --prefix)/share/zsh-completions" ]]; then
  fpath="$(brew --prefix)/share/zsh-completions" $fpath
fi
# Linux (common path)
if [[ -d "/usr/share/zsh/functions/Completion" ]]; then
  fpath="/usr/share/zsh/functions/Completion" $fpath
fi

2. Load and initialize completion with the insecure‑skip flag (or use a dump):

autoload -Uz compinit
compinit -i   # skip security checks; use -C to rely on a cached dump if you prefer

3. Apply a neutral set of zstyle options to make behavior identical:

zstyle ':completion:*' menu select   # show a menu when multiple matches
zstyle ':completion:*' group-name '' # group matches by description
zstyle ':completion:*' verbose true  # show descriptions

4. Source the snippet in ~/.zshrc after any plugin managers but before any custom completion definitions.

With these steps, completion behaves consistently, starts quickly, and retains the ability to add user‑specific completions later in the same file.