In Terminal.app, option+arrow keys no longer move by word

Restoring Option+Arrow Key Word Navigation in macOS Terminal

Learn how to fix the common issue where Option+Arrow keys stop working for word-by-word navigation in macOS Terminal, especially with Zsh and Oh My Zsh.

Many macOS Terminal users rely on the Option + Left Arrow or Option + Right Arrow key combinations for quick word-by-word navigation within the command line. This functionality is crucial for efficient editing and productivity. However, after updates, new installations, or configuration changes (especially involving Zsh and Oh My Zsh), users often find that these key bindings stop working as expected, instead producing strange characters or no movement at all. This article will guide you through diagnosing and resolving this common issue, ensuring your Terminal experience remains productive.

Understanding the Problem: Key Bindings and Shell Configuration

The Option + Arrow key behavior is not natively handled by the shell itself in the same way as Ctrl + Arrow might be in some environments. Instead, it relies on how the Terminal application interprets these key presses and what escape sequences it sends to the shell. The shell (like Zsh) then needs to have corresponding key bindings configured to understand these sequences and perform the desired action (moving by word).

When Option + Arrow stops working, it's typically due to a mismatch or misconfiguration in one of these areas:

1. Terminal.app's Key Bindings: The Terminal application itself might not be configured to send the correct escape sequences for Option + Arrow.
2. Shell (Zsh) Key Bindings: Zsh might not have the appropriate zle (Zsh Line Editor) key bindings to interpret the sequences sent by Terminal.app.
3. Oh My Zsh Interference: Oh My Zsh, a popular Zsh framework, can sometimes override or interfere with default key bindings, leading to unexpected behavior.

flowchart TD
    A[User Presses Option+Arrow] --> B{Terminal.app Configuration?}
    B -- Sends Escape Sequence --> C{Zsh Configuration?}
    C -- Has ZLE Binding? --> D[Move Cursor by Word]
    C -- No ZLE Binding --> E[Prints Junk / No Action]
    B -- Incorrect Sequence --> E

Flowchart illustrating the key binding process in macOS Terminal

Step-by-Step Solution: Configuring Terminal.app and Zsh

The most reliable solution involves ensuring both Terminal.app and Zsh are configured to work in harmony. We'll start by checking Terminal.app's settings and then move to Zsh's configuration.

1. Configure Terminal.app Preferences

Open Terminal.app, go to Terminal > Settings... (or Preferences... on older macOS versions). Navigate to the Profiles tab, select your active profile (usually Basic or Pro), and then go to the Keyboard sub-tab.

Ensure that the Use Option as Meta key checkbox is unchecked. This is a common culprit. Instead, we want specific key bindings for Option + Arrow.

Add or verify the following key bindings:

• Option + Left Arrow: Send string \033b
• Option + Right Arrow: Send string \033f

To add a binding, click the + button, press the key combination, select Send String to Shell, and enter the corresponding escape sequence. If they exist, ensure they match these values. These sequences correspond to backward-word and forward-word in most shells.

2. Configure Zsh Key Bindings

Next, you need to tell Zsh how to interpret these escape sequences. Open your ~/.zshrc file in a text editor (e.g., nano ~/.zshrc or code ~/.zshrc). Add the following lines to the end of the file:

bindkey '\eb' backward-word
bindkey '\ef' forward-word

• \eb is the escape sequence for Option + Left Arrow.
• \ef is the escape sequence for Option + Right Arrow.

These bindkey commands tell Zsh's Line Editor (ZLE) to map these sequences to the backward-word and forward-word functions, respectively. Save the file and then either restart your Terminal or run source ~/.zshrc to apply the changes.

3. Address Oh My Zsh Conflicts (If Applicable)

If you are using Oh My Zsh, it's possible that some plugins or themes might be overriding these bindings. While the above steps usually resolve the issue, if you still face problems, you might need to investigate your Oh My Zsh configuration. Look for any bindkey commands in your ~/.zshrc that might conflict, especially those related to Option or Meta keys. You can try placing the bindkey commands from the previous step after the line source $ZSH/oh-my-zsh.sh in your ~/.zshrc to ensure they take precedence.

# ~/.zshrc

# ... (other Zsh configurations, including Oh My Zsh source)

# Ensure these lines are present, preferably after Oh My Zsh is sourced
bindkey '\eb' backward-word
bindkey '\ef' forward-word

# To apply changes without restarting Terminal:
source ~/.zshrc

Example ~/.zshrc configuration for Option+Arrow key bindings

Verifying the Fix

Once you've applied the changes, open a new Terminal tab or window. Type a command with several words, for example: echo hello world this is a test. Now, try using Option + Left Arrow and Option + Right Arrow. Your cursor should now jump word by word. If it still doesn't work, double-check each step, paying close attention to the escape sequences and the exact placement of the bindkey commands in your ~/.zshrc.