Skip to content
Get packs

Guide · Open source

How to use zsh-autosuggestions: setup, keys and settings

Updated · written with AI from the project's own documentation and checked against our catalogue data

zsh-autosuggestions is a plugin for the zsh shell that suggests commands while you type, based on your command history and tab completions. The suggestion appears after the cursor in muted gray, and it is inspired by the autosuggestion feature of the Fish shell. This guide explains how the suggestions work, how to accept them, and how to change their behavior and appearance so you can use it in your own terminal.

zsh-autosuggestionszsh-users/zsh-autosuggestions · ★ 36.2k · MIT

Quick start

  1. 1Check your zsh version. Run zsh --version and confirm it is v4.3.11 or later, the stated requirement.
  2. 2Install the plugin. Follow the project's INSTALL.md, since the README does not list install commands inline.
  3. 3Start typing a command. Type the beginning of a command you have run before and look for the muted gray suggestion after the cursor.
  4. 4Accept the suggestion. Press the right arrow or End key with the cursor at the end of the line to accept it.
  5. 5Adjust the look or sources. Set ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE or ZSH_AUTOSUGGEST_STRATEGY in your config to change color or where suggestions come from.
  6. 6Add key bindings if needed. Use bindkey with an autosuggest widget, such as autosuggest-accept, to set your own key.

What zsh-autosuggestions does

As you type commands, you will see a completion offered after the cursor in a muted gray color. The plugin suggests commands based on history and completions, so long or complex commands you have run before can be finished with a single key press.

The README describes it as fast and unobtrusive, in the style of Fish shell's autosuggestions.

  • Requires zsh v4.3.11 or later.
  • Works only with zsh; it does not run in bash, Fish or other shells.
  • Suggestions come from your history by default and from tab completion when enabled.

Accept or run a suggestion

Press the right arrow key (the forward-char widget) or End (the end-of-line widget) with the cursor at the end of the buffer to accept the suggestion. It replaces the contents of the command line with the suggestion.

If you invoke the forward-word widget, the suggestion is only partially accepted, up to the point where the cursor moves.

  • Right arrow or End: accept the whole suggestion.
  • forward-word: accept part of the suggestion.

Configure the suggestion color and style

The default highlight is fg=8, which sets the foreground to color 8 from the 256-color palette. Set ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE to change it. If your terminal supports only 8 colors, use a number from 0 to 7.

You can also set a background color and make the text bold, underlined or standout. Config defaults are in src/config.zsh in the project.

ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=#ff00ff,bg=cyan,bold,underline"

Choose how suggestions are generated

ZSH_AUTOSUGGEST_STRATEGY is an array. Strategies are tried in order until one finds a suggestion. The three built-in strategies are history, completion and match_prev_cmd. The completion strategy requires the zpty module, which is included with zsh since 4.0.1.

For example, the following tries history first and falls back to completion.

  • history: the most recent match from history.
  • completion: a suggestion based on what tab completion would offer.
  • match_prev_cmd: like history, but prefers matches whose preceding history item matches the last executed command.
ZSH_AUTOSUGGEST_STRATEGY=(history completion)

Limit or ignore suggestions

Use ZSH_AUTOSUGGEST_HISTORY_IGNORE with a glob pattern to stop history suggestions that match it. For example, "cd *" stops cd commands from being suggested. ZSH_AUTOSUGGEST_COMPLETION_IGNORE does the same for the completion strategy.

ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE disables suggestions for large buffers. The README recommends the value 20, which helps when you paste large amounts of text.

ZSH_AUTOSUGGEST_HISTORY_IGNORE="cd *"

Key bindings and troubleshooting

The plugin provides widgets you can bind with bindkey, including autosuggest-accept, autosuggest-execute, autosuggest-clear, autosuggest-fetch, autosuggest-disable, autosuggest-enable and autosuggest-toggle. The README gives this example to accept with Ctrl+Space.

If suggestions do not appear, the README notes that iTerm2 users sometimes need to make sure the Background color and ANSI Bright Black color are different. When reporting a problem, include the smallest .zshrc that reproduces it, your zsh version from zsh --version, and your operating system.

  • Check your iTerm2 profile colors if suggestions are invisible.
  • Temporarily disable other plugins to isolate conflicts.
bindkey '^ ' autosuggest-accept

What people use it for

  • Re-running long git or docker commands by accepting the rest of a line from history.
  • Partially accepting a suggestion with forward-word to keep only the part you need.
  • Hiding noisy history entries such as cd commands with ZSH_AUTOSUGGEST_HISTORY_IGNORE.
  • Keeping large pasted text from triggering suggestions by setting ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE.

Frequently asked questions

Does zsh-autosuggestions work with bash or Fish?

No. The plugin works only with zsh, and it needs zsh v4.3.11 or later. It is inspired by Fish's autosuggestions but does not run inside Fish.

Is zsh-autosuggestions free?

The project is released under the MIT licence, as listed in the project details. The README does not discuss pricing.

How do I accept a suggestion?

Press the right arrow key or End with the cursor at the end of the command line. Use forward-word to accept only part of it.

How do I change the suggestion color?

Set ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE in your config. The default is fg=8, and you can add background colors, bold, underline or standout styles.

Why are my suggestions not showing?

The README notes that some iTerm2 users cannot see suggestions because the Background and ANSI Bright Black colors are the same. Check those profile colors, and temporarily disable other plugins to find conflicts.

What are the alternatives to zsh-autosuggestions?

The project lists zsh-syntax-highlighting, fish shell and zsh-history-substring-search as comparable projects. Fish shell gives similar suggestions natively but requires switching shells.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

zsh-autosuggestions suits people who use zsh every day and repeat long commands, because it adds Fish-style suggestions without changing shells. If you use bash or Fish, or you want no visual changes to your prompt or terminal, pick a different tool or shell.

Install options & downloads