[tmux.app]
tmux 3.8

Docs · Editors · Neovim 0.12 · tmux 3.8

Neovim + tmux: navigation, true color and clipboard

Neovim and tmux work well together once five things are set: vim-tmux-navigator for Ctrl+h/j/k/l across Neovim splits and tmux panes, a short escape-time (already 10 ms in tmux 3.5+), true color and undercurl, focus events, and the clipboard. Here is the whole setup, each part tested on tmux 3.8 and 3.4 with Neovim.

Updated Tested on tmux 3.88 min read

On this page
  1. Seamless Ctrl+h/j/k/l navigation with vim-tmux-navigator
  2. Escape delay: escape-time
  3. Alt key mappings (move lines with Alt+j/k) inside tmux
  4. 24-bit true color and undercurl
  5. Clipboard and focus events
  6. Cursor shape in Insert mode
  7. Zoom, sessions and restoring Neovim after a reboot
  8. Troubleshooting Neovim in tmux
  9. FAQ

Quick answer

What do I put in ~/.tmux.conf for Neovim?

~/.tmux.conf (Neovim essentials)
set -g default-terminal "tmux-256color"
set -as terminal-features ",xterm*:RGB"      # 24-bit color (use your outer $TERM)
set -as terminal-features ",xterm*:usstyle"  # undercurl + colored underlines
set -sg escape-time 10                       # default since 3.5; 500 before
set -g focus-events on                       # 'autoread' and FocusGained
set -s set-clipboard on                      # let Neovim copy via OSC 52

Then add vim-tmux-navigator to both sides, reload with tmux source-file ~/.tmux.conf, detach and reattach, and run :checkhealth in Neovim.

Versions: Neovim 0.12.6 is the current stable release (9 October 2026); we ran the tests with Neovim 0.9.5, the Ubuntu 24.04 package, and checked the 0.12.6 source for the clipboard and health-check behavior quoted here. vim-tmux-navigator at commit e41c431 (25 January 2026).

Escape delay: escape-time

tmux waits escape-time milliseconds after Esc to see whether more bytes follow (an arrow key or an Alt combination also start with Esc). Before tmux 3.5 the default was 500 ms, which makes leaving Insert mode in Neovim feel sluggish. Since 3.5 the default is 10 ms.

~/.tmux.conf
set -sg escape-time 10

Keep the line if your config may run on older servers: Ubuntu 24.04 ships tmux 3.4 and Ubuntu 22.04 ships 3.2a. Neovim's :checkhealth reports it. This is the real output of Neovim 0.9.5 inside tmux 3.4 with no config:

:checkhealth nvim (tmux 3.4 defaults)
tmux ~
- ERROR `escape-time` (500) is higher than 300ms
  - ADVICE:
    - set escape-time in ~/.tmux.conf:
      set-option -sg escape-time 10
- WARNING `focus-events` is not enabled. |'autoread'| may not work.
Real screenshot · tmux 3.8The same check inside tmux 3.8 with escape-time 10, focus-events on and RGB set: every tmux item passes.
The same check inside tmux 3.8 with escape-time 10, focus-events on and RGB set: every tmux item passes.
How this was captured

Captured 2026-10-29 04:51 UTC from a real xterm window running tmux 3.8 on Ubuntu 24.04. Nothing is mocked up. The commands that set up the screen:

# ~/.tmux.conf: set -g focus-events on
# ~/.tmux.conf: set -as terminal-features ',xterm-256color:RGB'
tmux new-session -d -s work -x 100 -y 25
tmux send-keys -t work 'nvim --clean '"'"'+checkhealth nvim'"'"'' Enter
tmux send-keys -t work '/^tmux' Enter
tmux send-keys -t work zt

Do not set escape-time 0 to "be safe": on a slow SSH link an Alt key can then arrive as a separate Esc and letter. 10 is enough locally; use 20 to 50 over a slow connection.

Alt key mappings (move lines with Alt+j/k) inside tmux

A common Neovim mapping moves lines with Alt+j and Alt+k (:m .+1). If it works in a plain terminal but not in Neovim inside tmux, check these in order:

  1. macOS Option key. The terminal must send Option as Alt/Meta. iTerm2: Settings → Profiles → Keys → General, Left/Right Option key Esc+. Ghostty: macos-option-as-alt = true. Apple Terminal: Use Option as Meta Key. If Option types characters such as ∆, this is the cause.
  2. A tmux binding takes the key first. A config line such as bind -n M-j select-pane -D (common in pane-navigation snippets) catches Alt+j in every pane, and Neovim never sees it. List root bindings with tmux list-keys -T root | grep M- and remove or change the conflicting one.
  3. The key arrives split. With a very low escape-time and a slow link, tmux may pass Esc and j separately. Set escape-time to 10 or more as above.

We measured how Neovim saw the bytes Esc j typed into a tmux client, with a mapping on <M-j>:

tmuxescape-timeEsc and j arriveNeovim saw
3.8 and 3.40, 10 or 500together (a real Alt+j)<M-j>
3.410100 ms apart (laggy link)Esc, then j
3.4500100 ms apart<M-j>
3.810100 ms apart<M-j>
3.810, with bind -n M-j select-pane -Dtogethernothing (tmux took it)

Test: Neovim 0.9.5 started with --clean and a mapping that records the key, a tmux client in a pseudo-terminal, bytes written to it from a script. A 30 ms gap was still read as <M-j> on both versions.

24-bit true color and undercurl

Inside tmux, TERM should be tmux-256color. tmux then needs to know that the terminal outside it can draw 24-bit color (the RGB feature) and curly, colored underlines (usstyle), which Neovim uses for diagnostics.

~/.tmux.conf
# TERM inside tmux: 256 colors, italics
set -g default-terminal "tmux-256color"

# The outer terminal supports 24-bit color. Match its $TERM:
# xterm* covers xterm-256color and xterm-ghostty; add e.g. ",xterm-kitty:RGB"
set -as terminal-features ",xterm*:RGB"

# Undercurl and colored underlines for LSP diagnostics
set -as terminal-features ",xterm*:usstyle"
~/.config/nvim/init.lua
vim.opt.termguicolors = true

Restart the tmux server (tmux kill-server) or at least detach and reattach after changing terminal-features: features are worked out when a client attaches. Then check what tmux detected with tmux display -p '#{client_termfeatures}'; you want RGB in the list.

What we tested (client TERM=xterm-256color, no config)tmux 3.4tmux 3.8
COLORTERM=truecolor set in the outer terminalno RGBRGB detected (3.6+)
Undercurl \e[4:3m from the pane, without usstylenot passed to the terminal
The same with usstyle addedpassed through, including the underline color
Cursor shape \e[6 q (bar in Insert mode)passed through by default (cstyle is in the default xterm* features)

tmux 3.8 also asks the terminal for its name, and for Ghostty, iTerm2, WezTerm, foot and mintty turns on RGB, undercurl and more automatically. The lines above are still worth keeping for other terminals and older tmux. Color problems in general are on true color in tmux and colors look wrong.

Clipboard and focus events

~/.tmux.conf
# Tell Neovim when you switch to and from the pane ('autoread', FocusGained)
set -g focus-events on

# Let programs in tmux (Neovim with OSC 52) set your local clipboard
set -s set-clipboard on
~/.config/nvim/init.lua
vim.opt.clipboard = "unnamedplus"  -- y and p use the system clipboard
vim.opt.autoread = true            -- reload files changed outside Neovim

How Neovim copies inside tmux. Neovim picks the first clipboard tool it finds. On macOS that is pbcopy; on Linux with a desktop, wl-copy, xclip or xsel. On a server over SSH there is usually none of those, and inside tmux Neovim then uses tmux itself: in Neovim 0.12 it copies with tmux load-buffer -w - (the -w is used with tmux 3.2 and later) and pastes with tmux refresh-client -l plus save-buffer. -w sends the text on to your terminal with OSC 52, so a yank on a remote server lands in your laptop's clipboard if your terminal allows OSC 52 writes.

set-clipboard (tested on 3.8)tmux load-buffer -w (Neovim's tmux provider)OSC 52 sent by a program in the pane
external (default)reaches the terminalignored
onreaches the terminalreaches the terminal and becomes a tmux buffer

So the default works for Neovim's automatic tmux provider, and set-clipboard on is needed when Neovim sends OSC 52 itself, for example with vim.g.clipboard = "osc52" (Neovim 0.10+). Neovim's own docs warn that a multiplexer "may inhibit automatic OSC 52 support detection", which is why setting it explicitly helps inside tmux. Pasting from the system clipboard is usually easiest with your terminal's paste key; reading the clipboard through OSC 52 needs terminal support and permission. Copying in tmux itself (copy mode, copy-pipe, OSC 52 over SSH) is on the copy mode clipboard page.

focus-events on needs a detach and reattach to take effect. Without it, :checkhealth warns that 'autoread' may not work, because Neovim never hears that you came back to the pane after a git checkout in another one.

Cursor shape in Insert mode

Neovim switches to a bar cursor in Insert mode by sending \e[6 q. tmux passes it on when the outer terminal has the cstyle feature, which every xterm* terminal gets by default (we saw the sequence reach the terminal unchanged on 3.8 and 3.4). If your outer TERM does not start with xterm and the cursor stays a block, add it: set -as terminal-features ",alacritty:cstyle" (use your own TERM).

Zoom, sessions and restoring Neovim after a reboot

Zoom. Ctrl+b z makes the Neovim pane fill the window and back, so you can keep logs and a shell beside it and still get full-screen editing.

Restore after reboot. tmux sessions do not survive a reboot. The tmux-resurrect plugin saves and restores the layout, and can reopen Neovim from a Session.vim file:

~/.tmux.conf (with TPM and tmux-resurrect)
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @resurrect-strategy-nvim 'session'

Neovim has to write that session file, which the tmux-resurrect docs suggest doing with tpope/vim-obsession (:Obsess). Save with Ctrl+b Ctrl+s and restore with Ctrl+b Ctrl+r; setup and continuous saving are on the plugins page.

Troubleshooting Neovim in tmux

SymptomCause and fix
'tmux-256color': unknown terminal type.The machine has no terminfo entry for tmux-256color (old macOS ncurses, minimal containers). Copy it from a machine that has it: infocmp -x tmux-256color | ssh host -- tic -x -; install your distro's ncurses terminfo package; or fall back to set -g default-terminal "screen-256color".
Colors washed out, termguicolors looks wrongAdd RGB for your outer TERM and reattach; check #{client_termfeatures}.
Esc is slowescape-time is 500 (tmux before 3.5). Set it to 10.
Ctrl+h deletes a character instead of movingThe tmux binding is missing or is_vim did not match. tmux list-keys -T root C-h prints unknown key: C-h when the binding is missing; reload the config.
Ctrl+l no longer clears the shellUse Ctrl+b Ctrl+l with the bind C-l send-keys 'C-l' line above.
No undercurl, plain underlineAdd usstyle for your outer TERM.
Alt mappings do nothingSee Alt key mappings.

More fixes, including the Escape delay and undercurls, are on the troubleshooting page.

FAQ

How do I navigate seamlessly between Neovim and tmux panes with Ctrl+hjkl?

Install vim-tmux-navigator in Neovim (the lazy.nvim spec above) and add its is_vim bindings to ~/.tmux.conf (or set -g @plugin 'christoomey/vim-tmux-navigator' with TPM). tmux then sends Ctrl+h/j/k/l to Neovim when the pane runs Neovim, and Neovim hands control back to tmux at the edge of its splits.

Why can't I move lines with Alt in Neovim inside tmux?

Usually because the Option key on macOS is not sent as Alt, or because a tmux binding such as bind -n M-j catches the key before Neovim. Fix the terminal setting, remove the conflicting binding, and keep escape-time at 10 or more.

What escape-time should I use for Neovim?

10 milliseconds, which is the default since tmux 3.5. Neovim's health check reports an error above 300.

Do I need set-clipboard on for Neovim?

Only if Neovim sends OSC 52 itself (vim.g.clipboard = "osc52"). Neovim's automatic tmux clipboard provider uses tmux load-buffer -w, which reaches your terminal with the default external setting.

Should I use nvim-tmux-navigation or vim-tmux-navigator?

nvim-tmux-navigation (alexghergh) is a Lua rewrite of vim-tmux-navigator for Neovim 0.7 and later. vim-tmux-navigator is the original, works in Vim too, and is the one we tested here. With either plugin the tmux side is the same idea: an is_vim check and bind -n C-h/j/k/l.

Keep learning

Something wrong or out of date on this page? Email hello@tmux.app and we will fix it.