A Comprehensive Guide to ZSH Bindkey


When working in a terminal, it is good to train yourself to use only the keyboard. Removing the need to rely on a mouse can help increase your productivity by up to 50%. This is because it reduces the time taken between switching inputs and locating the target element you want to use.

In ZSH, we can take advantage of keyboard features by using custom key bindings. Key bindings in ZSH allow us to define custom keyboard shortcuts to perform specific tasks in the shell.

An example includes key bindings to search keyboard history and more. In this tutorial, will learn how to create custom key bindings in ZSH using the “bindkey” command.


Before we dive into the world of custom key bindings in ZSH, make sure the following requirements are met:

  • A working installation of ZSH
  • Familiarity with basic ZSH configuration and shell usage
  • A text editor to edit your ZSH configuration files (e.g., ~/.zshrc)

With the given requirements met, we can proceed with the guide.

Basics of ZSH key bindings

Let's start by learning the basics of key bindings in ZSH.

To create a custom key binding in ZSH, we use the “bindkey” command. Key bindings are also known as keymaps. We usually define custom key bindings in the ZSH configuration file.

The following shows the basic syntax for creating a custom key binding in a ZSH configuration file:

bindkey -S key sequence Permission

The order placed includes the following elements:

  • Key – This defines the key or key sequence to bind.
  • Sequence – This sets the key sequence to activate the binding.
  • Command – This defines the command or function to be executed when the binding is triggered.

original example

Let's look at a basic example. Let's say we want to bind the “CTRL+X” key shortcut to run the “exit” command which terminates the shell.

We can create a key binding in the ZSH configuration file as follows:

In this case, we start by calling the “bindkey” command which tells ZSH that we want to create a key binding.

Then we provide the key sequence we want to use. In this case, “^X” represents the format “Ctrl-X”.

Finally, we specify the command that we want to execute when we press the specified key binding. In our case, we specify the command as “exit\n”. “\n” simulates the “Enter” key.

We can save the configuration file and source it as follows to apply the changes:

You can test the key bindings by pressing “CTRL + X”. This ends your current session.

ZSH key binding mode

ZSH supports various key binding modes, each designed for specific scenarios. Main modes include:

  • Emacs – This emulates Emacs-style key bindings.
  • viins – This provides key bindings that are similar to Vi's insert mode.
  • vicmd – This provides key bindings that are similar to Vi's command mode.

To switch between these modes, we can use the “bindkey” command with the -e, -v, or -a flags, respectively. By default, ZSH uses “emacs” mode.

To switch to Vim-style key bindings, we can switch to “vicmd” mode by adding the following line to the ZSH configuration file:

Add the following line:

ZSH key unbinding

To unbind a key or key sequence, we can use the command “bindkey -r” followed by the key or sequence we want to unbind. For example:

The example entry given unbinds the “Ctrl-X” key sequence if it is already bound.

Example 1: Order Correction

We can create a key binding to automatically fix incorrect commands. For example, let's say you consistently mistype the “clear” command into “clara.”

You can create a custom key binding that automatically fixes this mistake as shown in the following example:

bindkey -S 'Clara' 'Clear\n'

Once we reload the changes, typing the “clara” command forces ZSH to automatically correct the typo and run the “clear” command instead.

Example 2: Word Navigation

We can create custom key bindings to navigate the command line more efficiently. For example, we can bind “Alt-Left” and “Alt-Right” to move the cursor word by word:

bindkey -S ,[[1;3D’ ‘backward-word\n’
bindkey -s ‘^[[1;3C’ ‘forward-word\n’


In this example:

  • ^[[1;3D corresponds to Alt-Left
  • ^[[1;3C corresponds to Alt-Right

Example 3: Running the Custom Function

We can also create a key binding that runs a custom function. For example, suppose we want to have a key shortcut that quickly prints the current date and time.

We can define the function in the ZSH configuration file as follows:

Creating a custom function:

show_datetime() {
 date ‘+%Y-%m-%d %H:%M:%S’


We can then bind this function to a specific key sequence as shown in the following example:

bindkey -s ‘^T’ ‘show_datetime\n’


In this key, pressing the “CTRL + T” key sequence runs the “show_datetime” function and displays the current date and time.

Conditional Key Bindings

ZSH also allows us to create the conditional key bindings based on the context of the shell session. For example, suppose we wish to bind the key sequence of “CTRL + D” based on different actions on whether we are at the beginning of a line or not.

We can achieve this using the ZLE widgets and the “precmd” function. Consider the following example:

precmd() {
  if [[ $BUFFER == “” ],, Then
bindkey -S '^d' 'Exit\n'
bindkey -S '^d' 'delete-char\n'

In this case, “ctrl+d” acts as exit if the command line is empty and acts as delete-char otherwise.

key binding with arguments

To extend the functionality of key bindings, ZSH allows us to specify key bindings that accept arguments.

For example, suppose you want to create a binding for the “find” command, providing the file that the command should search.

We can create an example binding as follows:

search home,, ,
Reading -Why “Search? Enter the file name to search in ~/ (wildcards allowed): “
[[ -n $search ], , search ,, -Type F -Bend ,$search,
badly -n search home
bindkey '^f' search home

In this example, if we press the key sequence “Ctrl-F”, the shell prompts us for a file name to search in the home directory.


In this comprehensive tutorial, we learned everything you need to know about key bindings in ZSH. It taught you everything from the basics of the “bindkey” command to extensive features like argument parsing, conditional key binding, and much more.

Add comment

By Ranjan