By default, zsh on Debian keeps 30 commands in memory and writes none of them to disk. Install zsh-autosuggestions on top of that and it looks broken, because the plugin suggests from history and every new terminal starts with an empty one. The grey completion you saw in a screenshot never appears until you tell zsh where to save history and how much to keep.
This guide sets up zsh autosuggestions properly: the Debian package, a git clone on Rocky Linux where no package exists, and the Oh My Zsh plugin. It also covers the history settings that make suggestions survive a new session, the completion strategy, a readable colour and the keys that accept a suggestion. Everything below was tested on Debian 13 and Rocky Linux 10 in October 2026 with zsh 5.9 and zsh-autosuggestions 0.7.1.
Install zsh and zsh-autosuggestions on Debian
Debian ships the plugin as a package, so on Debian you do not need git or a plugin manager at all. Install zsh and the plugin together:
sudo apt install -y zsh zsh-autosuggestionsThe package only drops a script on disk and changes nothing in your shell, so you need its path for ~/.zshrc. List the files it installed:
dpkg -L zsh-autosuggestions | grep -E "\.zsh$"There is exactly one script to source. Every ~/.zshrc on Debian in this guide points at this path:
/usr/share/zsh-autosuggestions/zsh-autosuggestions.zshDebian also packages zsh-syntax-highlighting (we had 0.8.0-2 installed alongside), but we did not configure it in this test, so it stays out of the files below. Next, make zsh your login shell. chsh writes the new shell into /etc/passwd, and $USER expands to your own login:
sudo chsh -s /usr/bin/zsh "$USER"
getent passwd "$USER"The last field of the passwd line should now read /usr/bin/zsh. On our VM, where the login is josphat:
josphat:x:1000:1000::/home/josphat:/usr/bin/zshThe change applies to new logins only, so your current session keeps its old shell until you log out and back in. Everything in the next section also works in a zsh you start by hand, so there’s no need to log out right now.
Make zsh save your history
This step is the one most guides skip, and it is why “zsh autosuggestions not working” is such a common complaint. The plugin’s default strategy is history, so it can only suggest commands that are in the current shell’s history list. Debian’s /etc/zsh/zshrc sets no history variables at all, which leaves zsh on its compiled-in defaults. Because the next command overwrites ~/.zshrc, copy any existing one first:
cp ~/.zshrc ~/.zshrc.bakThen start with a ~/.zshrc that only sources the plugin, and ask zsh what it’s working with:
echo "source /usr/share/zsh-autosuggestions/zsh-autosuggestions.zsh" > ~/.zshrc
zsh -ic "echo HISTFILE=\$HISTFILE SAVEHIST=\$SAVEHIST HISTSIZE=\$HISTSIZE; echo strategy=\$ZSH_AUTOSUGGEST_STRATEGY style=\$ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE"An empty HISTFILE and SAVEHIST=0 mean nothing is ever written to disk, and HISTSIZE=30 caps what the running shell remembers:
We proved the effect in tmux. With that one-line ~/.zshrc, we ran systemctl list-timers --all --no-pager, exited, opened a fresh zsh and typed systemctl list-t. No suggestion appeared, because the previous session’s history died with it. With the history block below in place, the same test drew the rest of the command in grey (imers --all --no-pager, escape code 90) as soon as the prefix matched.
Autosuggestions not showing in a new terminal
If suggestions work inside one terminal but vanish when you open another, history is not being saved. Open your zsh config in any editor. We use vi here because minimal Debian and Rocky installs ship only vim-tiny or vim-minimal, which provide vi but not vim, and nano works just as well:
vi ~/.zshrcAdd the history settings next to the source line. These five lines are a subset of the full file we tested in the next section:
HISTFILE=~/.zsh_history
HISTSIZE=10000
SAVEHIST=10000
setopt INC_APPEND_HISTORY HIST_IGNORE_DUPS
source /usr/share/zsh-autosuggestions/zsh-autosuggestions.zshEach line does one job:
HISTFILE: where history is writtenHISTSIZE: commands kept in memory per shellSAVEHIST: commands written to the fileINC_APPEND_HISTORY: write each command as you run itHIST_IGNORE_DUPS: skip a command repeated back to back
INC_APPEND_HISTORY is the one we’d never leave out. Without it, zsh writes history only when a shell exits, so a second terminal opened while the first is still running sees nothing from it. Open a new terminal (or run exec zsh), run a few commands, and they’ll be suggested in every shell you start afterwards.
Tune zsh autosuggestions: strategy, colour and keys
Once history is saved, three settings decide how useful the suggestions feel: where they come from, how they look and how you accept them. This is the full ~/.zshrc we ended with on Debian 13. Back up your current one, then open it again:
cp ~/.zshrc ~/.zshrc.bak
vi ~/.zshrcReplace the contents with this file. It’s the exact file from the lab, and zsh -n reported it syntax-ok:
autoload -Uz compinit && compinit
HISTFILE=~/.zsh_history
HISTSIZE=10000
SAVEHIST=10000
setopt INC_APPEND_HISTORY HIST_IGNORE_DUPS
ZSH_AUTOSUGGEST_STRATEGY=(history completion)
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE='fg=244,underline'
source /usr/share/zsh-autosuggestions/zsh-autosuggestions.zsh
bindkey '^ ' autosuggest-accept
bindkey '^[f' forward-wordZSH_AUTOSUGGEST_STRATEGY=(history completion) tries history first and falls back to tab completion when nothing in history matches. The fallback silently does nothing without compinit. Typing systemctl stat with no matching history gave no suggestion until we added the autoload -Uz compinit && compinit line, and after that zsh offered us to complete systemctl status. If you already load completion elsewhere, for example through our bash completion in zsh setup, keep a single compinit call and make sure it runs before the plugin.
The default highlight style is fg=8, which is colour slot 8 of your terminal palette, so how visible it is depends entirely on your theme. We set fg=244,underline, a fixed 256-colour grey with an underline, and the captured pane showed exactly that colour with the underline applied. That reads clearly on a dark background and doesn’t look like text you’ve already typed, which matters when the suggestion is a destructive command.
Three keys accepted suggestions in our tmux tests, starting from a history entry of journalctl -u ssh --since today --no-pager and a typed prefix of journalctl -u:
- Right arrow: accepts the whole suggestion (plugin default)
- Ctrl+Space: accepts the whole suggestion (our
bindkey '^ 'line) - Alt+f: accepts up to the start of the next word (forward-word)
Alt+f is the one to learn if you reuse long commands with a different last argument. The first press accepted only the space before ssh and left the rest suggested. We only captured that first press, but the plugin README lists forward-word as a partial-accept widget, so repeated presses take the suggestion a word at a time and you stop where your command differs. In zsh’s default emacs keymap Alt+f is already forward-word, so our bindkey '^[f' line is redundant there and only matters if zsh started in vi mode, which it does when $EDITOR or $VISUAL contains vi. Ctrl+Space is different: by default it runs set-mark-command, and our bindkey '^ ' line rebinds it to accept the suggestion. That keeps your right hand on the home row, and with the cursor at the end of the line it does the same job as Right arrow.
Install zsh-autosuggestions on Rocky Linux 10
Rocky Linux 10 has zsh 5.9 in its base repositories but no package for the plugin, and EPEL does not carry one either. Install zsh and git, then check:
sudo dnf -y install zsh git
dnf -q list zsh-autosuggestionsOn our Rocky 10 VM the list came back empty both before and after EPEL was enabled, which is the error below.
Error: No matching Packages to list
dnf prints this when no enabled repository has a package by that name, and it was the only line of output:
Error: No matching Packages to listThere is no repository fix here, so the upstream git repository is the install method on Rocky, and it works the same on any distro without a package. Clone it into your home directory:
git clone --depth 1 https://github.com/zsh-users/zsh-autosuggestions ~/.zsh/zsh-autosuggestions
cat ~/.zsh/zsh-autosuggestions/VERSIONOur clone tracks the default branch rather than a release tag. Ours was commit 85919cd from 2025-06-24, and its VERSION file still read v0.7.1, the same release number Debian packages, so the settings in this guide behaved the same on both. Switch your login shell to zsh. On Rocky the binary is /bin/zsh:
sudo usermod -s /bin/zsh "$USER"Rocky’s /etc/zshrc does not set any history variables either, so the history block is just as necessary here. Back up any existing file, then create the config:
cp ~/.zshrc ~/.zshrc.bak 2>/dev/null
vi ~/.zshrcPoint the source line at the clone instead of the Debian path. The four history lines are the same as on Debian:
HISTFILE=~/.zsh_history
HISTSIZE=10000
SAVEHIST=10000
setopt INC_APPEND_HISTORY HIST_IGNORE_DUPS
source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zshThe strategy, colour and bindkey lines from the Debian file work here unchanged if you want them. To check that the plugin actually loaded, count the widgets it registers:
zsh -ic 'print -r -- widgets=${#${(M)${(k)widgets}:#autosuggest-*}}'A loaded plugin registers nine autosuggest-* widgets. If you get widgets=0, the source path is wrong or the line sits in a file zsh never reads:
widgets=9We also called the plugin’s history strategy directly with the prefix sudo dnf up, and it returned sudo dnf upgrade --refresh -y from the saved history:
We checked it that way because tmux 3.4 aborted with “server exited unexpectedly” on our Rocky 10.1 VM, so the live-typing test from Debian could not run there. The plugin itself had no trouble.
Enable the plugin in Oh My Zsh
Oh My Zsh does not bundle zsh-autosuggestions, so you clone it into the custom plugins directory and add one word to the plugins line. We ran this part on the Debian VM. The installer and the clone need git and curl:
sudo apt install -y git curlIts unattended installer writes a fresh ~/.zshrc. We moved our hand-written one aside first, so the manual source line and the Oh My Zsh plugin couldn’t both load the plugin:
mv ~/.zshrc ~/.zshrc.manual
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattendedThe installer ends with “Run zsh to try it out.” and leaves ZSH_THEME="robbyrussell" and plugins=(git) in the new file. If you have not installed Oh My Zsh before, the full zsh and Oh My Zsh install guide covers themes and the other bundled plugins. Clone the plugin and add it to the list:
git clone --depth 1 https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
sed -i "s/^plugins=(git)/plugins=(git zsh-autosuggestions)/" ~/.zshrc
grep -n "^plugins=" ~/.zshrcThe sed only matches the stock plugins=(git) line, so if you’ve already edited that list, add zsh-autosuggestions by hand inside the parentheses. Ours now read:
76:plugins=(git zsh-autosuggestions)You do not need the history block with Oh My Zsh, because its lib/history.zsh already sets HISTFILE to ~/.zsh_history and raises SAVEHIST to 10000. In a new shell with docker compose logs -f --tail 50 in history, typing docker comp brought up the rest of the command in grey after the robbyrussell arrow prompt. Theme choice does not affect the plugin, so it sits fine under a heavier prompt such as Powerlevel10k. The same steps apply on a Mac, where our zsh setup for macOS gets you to this point.
Settings and keys reference card
The history and plugin values in this card were read from the lab or set in the tested ~/.zshrc files above, and the key defaults are zsh’s emacs keymap. The “Default” column is what you get with nothing but the source line on Debian, which is the state that makes the plugin look broken.
| Setting or key | Default | What we used | Effect |
|---|---|---|---|
| HISTFILE | empty | ~/.zsh_history | History survives closing the shell |
| HISTSIZE | 30 | 10000 | Commands kept in memory |
| SAVEHIST | 0 | 10000 | Commands written to the file |
| setopt INC_APPEND_HISTORY | off | on | New shells see commands from shells still open |
| ZSH_AUTOSUGGEST_STRATEGY | history | (history completion) | Falls back to tab completion, needs compinit |
| ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE | fg=8 | fg=244,underline | Same grey on every 256-colour theme |
| Right arrow | accept all | unchanged | Takes the whole suggestion |
| Ctrl+Space | set-mark-command | bindkey ‘^ ‘ autosuggest-accept | Takes the whole suggestion |
| Alt+f | forward-word (emacs keymap) | bindkey ‘^[f’ forward-word | Partial accept; binding only needed in vi mode |
| Plugin path, Debian | /usr/share/zsh-autosuggestions/zsh-autosuggestions.zsh | From the zsh-autosuggestions package | |
| Plugin path, Rocky | ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh | From git, no package in BaseOS or EPEL | |
| Plugin path, Oh My Zsh | $ZSH_CUSTOM/plugins/zsh-autosuggestions | Enabled through plugins=() | |
If you only change one thing from this card, make it the three history lines, because every other setting depends on the plugin having history to read. Every option the plugin accepts is listed in the zsh-autosuggestions README. If you’re still choosing a shell, our comparison of Linux and macOS shells covers fish, which has this feature built in.
