Bitdoze Logo
10 min read
linux
Dragos

How to Enable Command Autocomplete in ZSH

Learn how to enable tab completion, zsh-autosuggestions, and zsh-autocomplete plugins in ZSH for faster terminal workflows.

How to Enable Command Autocomplete in ZSH
#Zsh#Terminal#Shell

ZSH has a powerful completion system, but it doesn’t do everything out of the box. You need to enable the built-in tab completion and optionally add plugins for inline suggestions. This guide covers all three layers: ZSH’s native completion system, the zsh-autosuggestions plugin, and the zsh-autocomplete plugin.

ZSH comes pre-installed on macOS (since Catalina). On Linux, you’ll need to install it first.

Related ZSH guides:

Understanding ZSH completion vs autosuggestions

These terms get mixed up constantly. Here’s what each one actually does:

Built-in completion (compinit) — ZSH’s native completion system. When you press Tab, it shows possible completions for commands, options, filenames, variables, and more. It’s context-aware: it knows that git ch<Tab> should show checkout and cherry-pick, not random files. This is the foundation — everything else builds on it.

zsh-autosuggestions — A plugin that shows a grayed-out suggestion as you type, based on your command history. Think of it as fish shell’s inline suggestions ported to ZSH. You type dock and it suggests docker ps from your history in muted text. Press → to accept the suggestion. This is the most popular ZSH autocomplete plugin with over 35,000 GitHub stars.

zsh-autocomplete — A different plugin (by Marlon Richert) that shows a real-time dropdown menu of completions as you type, without pressing Tab. More like an IDE’s autocomplete. You type git and a list of subcommands appears below the prompt immediately. Fewer stars (~6,600) but a different UX approach.

Most people want built-in completion + zsh-autosuggestions. That’s the standard setup.

Step 1: Enable ZSH’s built-in completion system

ZSH’s completion system (compinit) needs to be initialized. If you’re using Oh My Zsh, this is already done for you. If you’re running plain ZSH, add this to your ~/.zshrc:

autoload -Uz compinit && compinit

This loads the completion system and initializes it. Without this line, basic Tab completion won’t work properly — you’ll only get filename completion, not context-aware command completions.

To speed up compinit (it can be slow because it checks many files on startup), you can cache the dump file:

# Rebuild the dump file only once a day
autoload -Uz compinit
if [[ -n ${ZDOTDIR:-$HOME}/.zcompdump(#qN.mh+24) ]]; then
  compinit
else
  compinit -C
fi

The -C flag skips the security check and uses the cached dump file. The conditional rebuilds it only if the dump is older than 24 hours.

Useful completion styles

Add these to your ~/.zshrc after compinit to improve the default completion behavior:

# Case-insensitive completion
zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}'

# Menu selection — use arrow keys to navigate completions
zstyle ':completion:*' menu select

# Group completions by type (commands, files, options)
zstyle ':completion:*' group-name ''

# Show descriptions for completions
zstyle ':completion:*' format '%F{yellow}-- %d --%f'

# Colorize file completions
zstyle ':completion:*' list-colors "${(s.:.)LS_COLORS}"

With menu select, Tab shows completions in a navigable menu. Arrow keys move through it, and Enter selects.

Step 2: Install zsh-autosuggestions

This plugin gives you fish-like inline suggestions from your history. There are two ways to install it.

Option A: With Oh My Zsh

If you’re already using Oh My Zsh:

# Clone the plugin into Oh My Zsh's custom plugins directory
git clone https://github.com/zsh-users/zsh-autosuggestions \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

Then edit ~/.zshrc and add zsh-autosuggestions to your plugins list:

plugins=(git zsh-autosuggestions)

If you don’t have Oh My Zsh installed yet:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Option B: Manual install (without Oh My Zsh)

git clone https://github.com/zsh-users/zsh-autosuggestions ~/.zsh/zsh-autosuggestions

Add this to your ~/.zshrc:

source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh

Option C: With Homebrew (macOS)

brew install zsh-autosuggestions

Add to ~/.zshrc:

source $(brew --prefix)/share/zsh-autosuggestions/zsh-autosuggestions.zsh

Reload your shell

source ~/.zshrc

Or just open a new terminal tab.

Step 3: Test it

Start typing a command you’ve used before. You should see a grayed-out suggestion appear after your cursor. For example, type ec and it might suggest echo "hello" from your history.

Key bindings for zsh-autosuggestions:

Action Key
Accept full suggestion → (right arrow) or End
Accept one word of suggestion Alt+F or Esc then F
Clear suggestion Ctrl+Space
Toggle suggestions on/off Bind with autosuggest-toggle

You can also accept with Ctrl+E (end-of-line) if your keybindings support it.

Customizing zsh-autosuggestions

Add these to ~/.zshrc after the source line (or in $ZSH_CUSTOM if using Oh My Zsh).

Change the suggestion color

The default is fg=8 (dark gray). Adjust if it’s hard to read in your terminal:

ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=240"

Or use a hex color:

ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=#666666"

Change the suggestion strategy

By default, suggestions come from your command history. You can also use tab-completion results or a combination:

# Try history first, fall back to completion system
ZSH_AUTOSUGGEST_STRATEGY=(history completion)

# Only use history (default, fastest)
ZSH_AUTOSUGGEST_STRATEGY=(history)

# Like history, but prioritizes matches from after the same previous command
ZSH_AUTOSUGGEST_STRATEGY=(match_prev_cmd)

Using (history completion) is slower because it runs the completion engine for every keystroke. Stick with (history) unless you want completions from commands you haven’t run before.

Disable suggestions for large pasted buffers

When you paste a large block of text, autosuggestions can lag. Set a buffer size limit:

ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE=20

Suggestions are disabled for any input longer than 20 characters.

Bind Ctrl+Space to accept suggestions

bindkey '^ ' autosuggest-accept

Optional: Install zsh-autocomplete for real-time menus

If you want IDE-style completions that appear as you type (without pressing Tab), install zsh-autocomplete instead of or alongside zsh-autosuggestions:

git clone --depth 1 -- https://github.com/marlonrichert/zsh-autocomplete.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autocomplete

Add to your plugins list in ~/.zshrc:

plugins=(git zsh-autosuggestions zsh-autocomplete)

Or without Oh My Zsh:

git clone --depth 1 -- https://github.com/marlonrichert/zsh-autocomplete.git ~/.zsh/zsh-autocomplete
source ~/.zsh/zsh-autocomplete/zsh-autocomplete.plugin.zsh

Note: Remove any compinit calls from your .zshrc — zsh-autocomplete handles initialization itself.

Important caveat: zsh-autocomplete and zsh-autosuggestions do different things and can conflict visually. Many users run both, but if the UI feels cluttered, pick one. zsh-autosuggestions is more popular and lightweight. zsh-autocomplete is heavier but shows more completions.

Putting it all together

Here’s a minimal ~/.zshrc with all the essentials:

# Oh My Zsh installation (if using)
export ZSH="$HOME/.oh-my-zsh"
plugins=(git zsh-autosuggestions zsh-syntax-highlighting)
source $ZSH/oh-my-zsh.sh

# Completion styles
zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}'
zstyle ':completion:*' menu select

# Autosuggestions config
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=240"
ZSH_AUTOSUGGEST_STRATEGY=(history)
ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE=20

Without Oh My Zsh:

# Completion system
autoload -Uz compinit
if [[ -n ${ZDOTDIR:-$HOME}/.zcompdump(#qN.mh+24) ]]; then
  compinit
else
  compinit -C
fi

# Completion styles
zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}'
zstyle ':completion:*' menu select

# Plugins
source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh
source ~/.zsh/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

# Autosuggestions config
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=240"
ZSH_AUTOSUGGEST_STRATEGY=(history)

The zsh-syntax-highlighting plugin is worth adding too — it colorizes commands as you type, so you can spot typos before hitting Enter.

Troubleshooting

Suggestions not showing up: Make sure compinit is loaded. Check with which _complete — if it returns nothing, the completion system isn’t initialized.

Gray text invisible in iTerm2: Go to iTerm2 Settings → Profiles → Colors. Make sure “Bright Black” (ANSI color 8) is different from your background color. They’re sometimes the same, making suggestions invisible.

Slow shell startup: If compinit is taking too long, use the cached version shown in Step 1. Also check if you’re loading too many plugins — each one adds startup time.

Completions not working after installing a new CLI tool: Some tools (like kubectl, docker, gh) require you to generate and source their completion scripts. For example:

# kubectl
kubectl completion zsh > ~/.zsh/completions/_kubectl

# docker
docker completion zsh > ~/.zsh/completions/_docker

# GitHub CLI
gh completion -s zsh > ~/.zsh/completions/_gh

Make sure ~/.zsh/completions is in your fpath before compinit:

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Want a batteries-included alternative? Fish Shell ships with autosuggestions, syntax highlighting, and rich completions out of the box. No plugins needed. See the Fish Shell vs Zsh comparison if you want to explore that option.

Which setup should you use?

Setup Best for Complexity
Built-in completion only Minimalists who want Tab-based completion Low
Built-in + zsh-autosuggestions Most users — history suggestions + Tab completion Low
Built-in + zsh-autosuggestions + zsh-syntax-highlighting Recommended trio — the “standard” ZSH power setup Low
Built-in + zsh-autocomplete IDE fans who want real-time dropdown menus Medium
All of the above Terminal maximalists Medium

For most people: Oh My Zsh (or plain ZSH) + zsh-autosuggestions + zsh-syntax-highlighting is the sweet spot. It’s fast, proven, and covers 90% of what you need.

Related Posts