How to fix modifier key issues in tmux?

Quick Answer

Add set-option -g extended-keys on to your ~/.tmux.conf to enable extended key sequences. If modifier keys still don't work, check your terminal's extended key support and configure terminal-features.

set-option -g extended-keys on

Detailed Explanation

Modern terminals support extended key sequences that allow modifier keys (Ctrl, Alt, Shift) to work properly with applications like tmux. If these keys aren't working, it's usually a configuration issue between tmux and your terminal.

Basic Extended Keys Setup

# In ~/.tmux.conf
set-option -g extended-keys on
set-option -g terminal-features 'xterm*:extkeys'

Common Problems and Solutions

  • Ctrl+arrow keys don't resize panes: Terminal may not support extended keys
  • Alt+keys don't work: Terminal might be capturing Alt for menus
  • Shift+function keys ignored: Need proper terminal feature detection

Manual Key Bindings

If extended keys don't work, manually bind the keys you need:

# Fix common Ctrl+arrow combinations
bind-key -n C-Left resize-pane -L 5
bind-key -n C-Right resize-pane -R 5
bind-key -n C-Up resize-pane -U 5
bind-key -n C-Down resize-pane -D 5

Testing Key Detection

# Check what tmux detects
tmux show-options -g extended-keys
tmux show-options -g terminal-features

# List current key bindings
tmux list-keys | grep -E "(C-|M-|S-)"

Pro Tip

Try pressing Ctrl+b ? to see all current key bindings. If you don't see your expected Ctrl/Alt combinations, they're not being detected properly.

Terminal-Specific Fixes

  • iTerm2: Enable "Report modifiers using CSI u" in Profiles → Keys
  • Alacritty: Ensure TERM=alacritty is set
  • Kitty: Extended keys are enabled by default
  • Terminal.app: Limited extended key support