tmux Cheatsheet

Troubleshooting

Use this tmux reference while you build software engineering projects, review code, or refresh the syntax you reach for most.

Troubleshooting

Symptom	Cause and fix
`no server running on /tmp/tmux-1000/default`	Nothing is running. Start with `tmux new`.
`sessions should be nested with care`	You are already inside tmux. Use `switch-client`, not `attach`.
`duplicate session: name`	It exists. `attach -t name` instead of `new -s name`.
Esc lags in Vim	`set -sg escape-time 10`
Colors wrong inside tmux	`default-terminal "tmux-256color"` plus a `terminal-overrides` `Tc` entry
Window shrinks to the smallest client	`setw -g aggressive-resize on`, or detach the other client with `attach -d`
Mouse selection copies the wrong thing	Hold `Shift` to use the terminal's own selection instead of tmux's
Clipboard does nothing	Set up `copy-pipe-and-conflict` for your platform, or `set -g set-clipboard on`
`$PATH` or `$EDITOR` stale in new panes	The server has an old environment. `tmux set-environment`, or `update-environment`
Window keeps renaming itself	`set -g allow-rename off`
Config change had no effect	`tmux source-file ~/.tmux.conf`, and check `show-options -g` for the real name
Option name rejected	It was renamed in a newer version. Check `tmux -V` against the manual.
Panes disappear after reboot	tmux is not persistent across reboots. Use resurrect plus continuum.
Prefix key does nothing	Another program grabbed it, or your config errored out. Run `tmux list-keys` to confirm it loaded.

tmux -vv new -s debug        # write a verbose server log to the cwd
tmux info                    # server, client, and terminal diagnostics
tmux list-keys | less        # what is actually bound
tmux show-options -g | less  # what is actually set
tmux kill-server             # start clean

When a config line fails, tmux prints the error and stops reading the file, so everything after that line is silently skipped. That is why "my config partly works" almost always means one bad line near the top.

tmux vs screen vs Zellij

	tmux	GNU screen	Zellij
Panes	Yes, first class	Yes, awkward	Yes
Scripting	Full command API	Limited	Yes, plus layouts as KDL
Config format	`tmux.conf` commands	`.screenrc`	KDL
Discoverability	`prefix ?`	Sparse	On-screen hints by default
Ubiquity	Almost everywhere	Everywhere, older boxes	Rare, install it yourself
Default prefix	`Ctrl-b`	`Ctrl-a`	`Ctrl-p`/`Ctrl-t` modes

Learn tmux because it is what is installed on the server you inherit. Zellij is friendlier for beginners, and screen is the fallback on very old systems where only screen exists.

Alternatives Inside a Terminal

Modern terminal emulators (WezTerm, kitty, Alacritty with a WM, iTerm2) all do splits and tabs natively, and they are faster because there is no extra process in the pipe. What they do not do is survive a dropped SSH connection or a closed terminal, because the shells are children of the GUI app.

The practical split most people land on:

Emulator splits for local work, where nothing needs to persist.
tmux on every remote host, always.

Version Differences

Options get renamed, and a config that works on 3.3 can fail on 2.6. tmux stops reading the file at the first error, so one bad line silently disables everything after it.

tmux -V

Version	Change
1.9	`default-path` removed, use `-c` on split and new-window
2.1	Mouse options merged into a single `mouse on`
2.4	Copy-mode commands moved to `send -X`, key tables changed
2.6	`set-clipboard` gained OSC 52 support
2.9	`-style` options replaced the old `-fg` / `*-bg` pairs; `new -A` added
3.0	`%if` / `%endif` conditionals in the config
3.1	XDG config path, `bind -N` descriptions
3.2	`display-popup`, `terminal-features`

# Guard a version-specific option
%if "#{>=:#{version},3.2}"
  set -g terminal-features ",*:usstyle"
%endif

# Or fall back silently on older builds
if-shell -b '[ "$(tmux -V | cut -d" " -f2 | tr -d "a-z")" -ge 29 ]' \
  'set -g status-style bg=colour235' \
  'set -g status-bg colour235'

Reading a Config Error

tmux source-file ~/.tmux.conf
# /Users/me/.tmux.conf:24: unknown option: mouse-select-pane

The line number is exact. Fix that line, re-source, repeat. Everything below line 24 was skipped, which is why "half my config works" is nearly always a single bad line rather than many.

Diagnostics Checklist

tmux -V                       # version, before anything else
tmux info | head -40          # server, terminal, and client details
tmux list-keys | grep <key>   # what a key is actually bound to
tmux show-options -g          # what is actually set globally
tmux show-options -gw         # window options
tmux list-sessions            # is the server even up
echo $TERM                    # inside vs outside tmux
tmux -vv new -s dbg           # verbose server + client logs in the cwd
tmux kill-server              # last resort, start clean

When something behaves differently than the docs say, check tmux -V first and tmux show-options -g <name> second. Between them they explain most surprises.