How to enable Vi keybindings in Zsh

Operators who already edit in vi or Vim can lose speed when the Zsh prompt keeps Emacs-style keybindings. Enabling Vi keybindings switches prompt editing to insert and command modes, so long commands and history entries can be corrected with familiar motions.

Zsh controls prompt editing through the ZLE line editor. The bindkey -v command switches the main keymap to Vi insert mode, and pressing Esc moves the prompt into Vi command mode for movement and history navigation.

Saving the settings in ~/.zshrc applies them to new interactive shells for that user. A syntax check catches startup-file mistakes before the next terminal opens, and a fresh zsh -ic check confirms the saved file changes the keymap instead of only changing the current shell.

1. Back up ~/.zshrc if the file already exists.

   $ cp ~/.zshrc ~/.zshrc.bak

   Skip this step if ~/.zshrc does not exist yet.

2. Add or update the Vi keybinding settings in ~/.zshrc.

   ~/.zshrc

   bindkey -v
   KEYTIMEOUT=1

   bindkey -v selects Vi-style line editing. KEYTIMEOUT=1 shortens the delay Zsh waits while reading multi-key sequences. Increase KEYTIMEOUT or remove that line if Alt or Meta key sequences stop working in a terminal profile.

3. Check the startup file for syntax errors.

   $ zsh -n ~/.zshrc

   No output from zsh -n means Zsh parsed the file without finding a syntax error.

4. Start a fresh interactive Zsh process and confirm that the main keymap points at Vi insert mode.

   $ zsh -ic 'bindkey -lL main'
   bindkey -A viins main

5. Check that a Vi command-mode movement binding is available.

   $ zsh -ic 'bindkey -M vicmd h'
   "h" vi-backward-char

6. Open a new terminal, press Esc at the prompt, and test command-mode movement keys such as h, j, k, and l.

   Terminal applications can intercept some key combinations before Zsh sees them. Test the keys in the terminal profile that will actually be used.