Tmux

  • Description: tmux terminal multiplexer — persistent shells over SSH, sessions/windows/panes, copy mode, and configuration.
  • My Notion Note ID: K2B-1-2
  • Created: 2020-06-08
  • Updated: 2026-05-15
  • License: Reuse is very welcome. Please credit Yu Zhang and link back to the original on yuzhang.io

Table of Contents

1. Overview

Persistent shells, decoupled from terminal emulator — primary reason to use tmux.

  • Close terminal / drop SSH / reboot laptop → shells keep running on server.
  • tmux attach restores pane layout + scrollback exactly.

Other capabilities (same architecture):

  • Windows (tabs) + panes (splits) inside one emulator window.
  • Scriptable session model — save, restore, launch from config or wrapper (tmuxinator, tmuxp).
  • Copy mode — scrollback as navigable buffer, vi or emacs keys.

Neighbours:

Tool Persistence Splits Scriptable layout Notes
screen Yes Yes (horizontal + vertical, 4.1+) Weak Older, GPLv3-licensed, simpler keybinds.
tmux Yes Yes (full grid) Strong ISC-licensed, active development.
Terminator/iTerm No Yes GUI-only Layout dies with the terminal process.

2. Installation and First Run

# Debian/Ubuntu
sudo apt install tmux

# Fedora/RHEL
sudo dnf install tmux

# macOS (Homebrew)
brew install tmux

# Arch Linux
sudo pacman -S tmux

Verify + start named session:

tmux -V              # e.g. tmux 3.4
tmux new -s work     # start a new session called "work"

Status bar: session name (left), window list (centre), host/time (right). Outside tmux → tmux ls lists running sessions.

3. Mental Model

Hierarchy, outside in:

  • Server — one background process per user. First tmux spawns it; tmux kill-server ends it. All sessions share one server.
  • Session — collection of windows. Detach → still running, reattach from any terminal.
  • Window — like a tab. Layout of one or more panes.
  • Pane — single pseudo-terminal running a shell or program. Split horizontally or vertically.

Prefix key starts every binding. Default C-b. This note uses C-x (rebound, see §8) — substitute C-b on a stock install. Chord, not held combo: press prefix, release, press next key.

4. Sessions

Action Shell command In-tmux binding
List sessions tmux ls C-x s
New named session tmux new -s <name> —
Attach to most recent tmux a (or tmux attach) —
Attach to specific tmux a -t <name> —
Detach (leave running) — C-x d
Rename current session — C-x $
Switch to another session — C-x s then select
Kill one session tmux kill-session -t <name> —
Kill server (all sessions) tmux kill-server —
  • Detach = normal exit; all panes keep running.
  • exit in the last pane of the last window → kills session.
  • tmux new -As work — attach to work if it exists, else create. Common in .bashrc for auto-attach on SSH login.

5. Windows

Binding (after prefix) Action
c Create new window
, Rename current window
& Kill current window (asks for confirmation)
n / p Next / previous window
0–9 Switch to window by index
w Interactive window list
f Find window by text
. Move window to a new index
' Prompt for window index to jump to
  • Status bar marks current window *, previously-active -.
  • C-x l → last-used window.
  • Default index starts at 0. base-index 1 → start at 1, aligns with number-row layout.

6. Panes

6.1 Pane Splits

Default binding Action
C-x % Split vertically (left/right)
C-x " Split horizontally (top/bottom)

Default mnemonic widely considered unmemorable → most configs rebind to C-x v / C-x h (or | / -). See §10.

6.2 Navigation and Resize

Binding Action
C-x <arrow> Move focus in that direction
C-x o Cycle to next pane
C-x ; Toggle to last active pane
C-x q Briefly show pane numbers; press number to jump
C-x <hold><arrow> Resize pane (repeat while held)
C-x M-<arrow> Resize in steps of 5
C-x z Zoom current pane to fill window (toggle)
C-x ! Promote pane to its own window
C-x x Kill current pane (asks for confirmation; exit also works, no prompt)
C-x { / C-x } Swap pane with previous / next
C-x <space> Cycle through layout presets

6.3 Layout Presets

After prefix, apply a built-in layout:

Binding Layout
C-x M-1 even-horizontal
C-x M-2 even-vertical
C-x M-3 main-horizontal
C-x M-4 main-vertical
C-x M-5 tiled
C-x M-6 main-horizontal-mirrored (tmux 3.5+)
C-x M-7 main-vertical-mirrored (tmux 3.5+)

Non-interactive: tmux select-layout tiled.

7. Copy Mode

Turns active pane → navigable buffer over screen + scrollback.

Binding (after prefix) Action
[ Enter copy mode
] Paste most recent buffer
= Choose buffer from list, then paste
# List all paste buffers

Navigation depends on mode-keys:

  • emacs (default) — C-Space start selection, M-w copy, C-r reverse search.
  • vi (setw -g mode-keys vi) — v start selection, y yank, / and ? search, n / N repeat.

Exit copy mode: q or Escape. System clipboard not built in — pipe buffer through external tool:

# Linux (X11): requires xclip
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"

# Wayland: replace xclip with wl-copy
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "wl-copy"

# macOS
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"

With set -g mouse on: hold Shift while selecting → bypasses tmux, uses terminal's native copy (targets system clipboard). Middle-click → pastes X11 primary selection.

8. Configuration

Config: ~/.tmux.conf (per-user) or /etc/tmux.conf (system-wide). Reload while running:

tmux source-file ~/.tmux.conf

Or bind a reload key (see sample) → C-x r.

Three directive families:

  • set -g <option> <value> — server/session options.
  • setw -g <option> <value> — window options (setw ≡ set-window-option).
  • bind <key> <command> — after-prefix; bind -n → no prefix; bind -r → repeat without re-pressing prefix.

8.1 Common Rebinds

# Replace the prefix
unbind C-b
set -g prefix C-x
bind C-x send-prefix          # press prefix twice to send literal C-x

# Saner split bindings
unbind '"'
unbind %
bind h split-window -h        # horizontal split (panes side-by-side)
bind v split-window -v        # vertical split (panes stacked)

# Vim-style pane navigation without prefix
bind -n M-Left  select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up    select-pane -U
bind -n M-Down  select-pane -D

# Window switching without prefix
bind -n S-Left  previous-window
bind -n S-Right next-window

# Mouse mode
set -g mouse on

# Vi keys in copy mode
setw -g mode-keys vi

# Faster repeat for resize
set -g repeat-time 600

# Reload config with prefix + r
bind r source-file ~/.tmux.conf \; display-message "tmux.conf reloaded"
  • bind -n ≡ bind -T root — root key table, prefix not required. Useful for chords like M-Left.
  • Check for collisions first — Alt-arrow is rebound by some terminal emulators.

9. Plugins (tpm)

tpm — de-facto plugin manager. Install:

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Append to ~/.tmux.conf:

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'

run '~/.tmux/plugins/tpm/tpm'    # must be last line

Inside tmux: prefix + I install, prefix + U update, prefix + alt-u remove unlisted.

Notable plugins:

  • tmux-sensible — opinionated defaults (escape time, history limit, mouse-friendly).
  • tmux-resurrect — saves session state to disk. prefix + C-s save, prefix + C-r restore.
  • tmux-continuum — auto-saves resurrect state every 15 min. Auto-restore on start is opt-in: set -g @continuum-restore 'on'.
  • tmux-yank — copy-mode bindings targeting system clipboard out of the box.

10. Sample Config

Minimal personal ~/.tmux.conf:

# --- prefix ------------------------------------------------------------------
unbind C-b
set -g prefix C-x
bind C-x send-prefix

# --- general -----------------------------------------------------------------
set -g mouse on
set -g history-limit 50000
set -sg escape-time 0
set -g default-terminal "screen-256color"
setw -g mode-keys vi

# --- pane splits -------------------------------------------------------------
bind h split-window -h -c "#{pane_current_path}"
bind v split-window -v -c "#{pane_current_path}"

# --- pane navigation (no prefix) --------------------------------------------
bind -n M-Left  select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up    select-pane -U
bind -n M-Down  select-pane -D

# --- window navigation (no prefix) ------------------------------------------
bind -n S-Left  previous-window
bind -n S-Right next-window

# --- quick reload ------------------------------------------------------------
bind r source-file ~/.tmux.conf \; display-message "tmux.conf reloaded"
  • -c "#{pane_current_path}" → new splits inherit current pane's cwd (rarely the default).
  • history-limit default 2000 → bumping costs only memory.

11. Pitfalls

  • ESC delay breaks Vim. tmux waits ≤500 ms after Escape to disambiguate meta-sequences. Fix: set -sg escape-time 0 (or 10).
  • Colours look washed out. Programs check TERM. Broad compatibility: set -g default-terminal "screen-256color". True-colour: "tmux-256color" + terminal-overrides ",xterm-256color:RGB".
  • Nested tmux sessions. SSH into remote, start tmux inside outer tmux → prefix ambiguous. Press prefix twice (C-x C-x here) → sends through to inner. Or bind a distinct prefix on the remote.
  • Mouse-mode copy. With mouse on, drag selects into tmux's paste buffer, not system clipboard. Hold Shift while selecting → bypass tmux, use terminal's native selection.
  • Status bar truncation in long sessions. Long pane titles or status segments shrink centre window list. Budget explicitly: set -g status-left-length 40, status-right-length 60.
  • exit vs kill-pane. Closing the last pane of the last window kills the session. Avoid accidental exit → detach first (C-x d).
  • Reload before debugging. Edits to ~/.tmux.conf don't apply until source-file (or server restart). Many "binding doesn't work" reports trace to this.

12. References