---
title: "How to Enable Command Autocomplete in ZSH"
description: "Learn how to enable tab completion, zsh-autosuggestions, and zsh-autocomplete plugins in ZSH for faster terminal workflows."
date: 2026-07-11
categories: ["linux"]
tags: ["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:**

- [How to Enable Syntax Highlighting in Zsh](https://www.bitdoze.com/enable-syntax-highlighting-zsh/)
- [Top 15 Oh My ZSH Plugins You Must Try](https://www.bitdoze.com/best-oh-my-zsh.plugins/)
- [Zoxide: The Smarter Way to Navigate Your Terminal](https://www.bitdoze.com/zoxide/)

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

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

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

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

```bash
# 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:

```zsh
plugins=(git zsh-autosuggestions)
```

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

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

### Option B: Manual install (without Oh My Zsh)

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

Add this to your `~/.zshrc`:

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

### Option C: With Homebrew (macOS)

```bash
brew install zsh-autosuggestions
```

Add to `~/.zshrc`:

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

### Reload your shell

```bash
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
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=240"
```

Or use a hex color:

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

```zsh
# 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
ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE=20
```

Suggestions are disabled for any input longer than 20 characters.

### Bind Ctrl+Space to accept suggestions

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

```bash
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`:

```zsh
plugins=(git zsh-autosuggestions zsh-autocomplete)
```

Or without Oh My Zsh:

```bash
git clone --depth 1 -- https://github.com/marlonrichert/zsh-autocomplete.git ~/.zsh/zsh-autocomplete
```

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

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

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

```bash
# 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`:

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

**Want a batteries-included alternative?** [Fish Shell](https://www.bitdoze.com/install-fish-shell-ubuntu/) ships with autosuggestions, syntax highlighting, and rich completions out of the box. No plugins needed. See the [Fish Shell vs Zsh](https://www.bitdoze.com/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.