Tmux

How to adjust escape-time in tmux?

Quick Answer

To adjust the escape-time in tmux, add set -sg escape-time 10 (or a lower value) to your ~/.tmux.conf file. The escape-time is the delay tmux waits after an escape character is input before treating it as part of a key sequence rather than a standalone ESC key. Reducing this value (default is 500ms) improves responsiveness in applications like Vim or Emacs, but setting it too low may cause issues with certain key sequences. A value between 0-10ms is recommended for most users.

# Add to ~/.tmux.conf set -sg escape-time 10

Detailed Explanation

The escape-time setting in tmux controls how long tmux waits after seeing an escape character (ASCII 27) before it treats it as a standalone key press rather than the beginning of an escape sequence (like those used for arrow keys or function keys).

Why Adjust Escape-Time?

There are several reasons to adjust the escape-time setting:

Improve responsiveness in modal editors - Vim and Neovim users often experience a noticeable delay when switching from insert to normal mode using the ESC key
Reduce latency in keyboard-driven applications - Lower values make applications that use escape sequences feel more responsive
Fix key sequence issues - Some terminal applications may behave incorrectly if the escape-time is too high or too low
Optimize remote sessions - SSH connections can benefit from adjusted escape-time values

Configuration Options

To configure the escape-time, add one of these lines to your ~/.tmux.conf file:

# Most responsive setting (best for Vim/Neovim users)
set -sg escape-time 0

# Balanced setting (recommended for most users)
set -sg escape-time 10

# Conservative setting (if you experience issues)
set -sg escape-time 50

# Default tmux setting
set -sg escape-time 500

The -sg flag indicates this is a server option with global scope.

Finding the Right Value

The ideal escape-time value depends on your setup and usage:

0-10ms: Ideal for local sessions and Vim/Neovim users
10-50ms: Good for remote sessions or if you experience issues with very low values
50-100ms: Conservative setting that should work reliably in most environments
500ms: Default tmux value, often considered too high for comfortable use

Testing Your Configuration

After modifying your ~/.tmux.conf, reload it with:

# In tmux command mode (Ctrl+b :)
source-file ~/.tmux.conf

To check your current escape-time setting:

# In tmux command mode (Ctrl+b :)
show-options -g escape-time

Potential Issues

Setting escape-time too low can cause problems:

Meta key combinations may not work properly (Alt/Option key sequences)
Some function keys or special key combinations might be misinterpreted
SSH sessions over high-latency connections may experience key sequence issues
Certain terminal applications might behave erratically

If you experience any of these issues, try increasing the escape-time value incrementally.

Pro Tip

For Vim users, you can also address ESC delay issues directly in Vim by adding these settings to your ~/.vimrc:

" Reduce Vim's internal timeout (milliseconds)
set timeoutlen=1000

" Eliminate delay when switching modes
set ttimeoutlen=0

" Tell Vim that tmux properly handles escape sequences
set term=screen-256color

This creates a more responsive experience even when tmux's escape-time can't be set to a very low value.

Comprehensive tmux.conf Setup

Here's a more complete tmux performance configuration that includes the escape-time setting:

# Reduce escape-time
set -sg escape-time 10

# Increase scrollback buffer size
set -g history-limit 50000

# Refresh status more often (default: 15)
set -g status-interval 5

# Enable focus events
set -g focus-events on

# Use 256 colors and true color support
set -g default-terminal "tmux-256color"
set -ga terminal-overrides ",*256col*:Tc"

←Back to FAQ Index