← Full reference

tmux

Terminal multiplexer — sessions that survive a dropped connection, windows and panes in one terminal

tmux starts a server that hosts sessions. A session contains windows (like tabs), and a window is split into panes. You can detach from a session — the programs inside keep running — and reattach later, including from another SSH connection.

Syntax

tmux                          # a new session, attached
tmux command [options]        # control the server from the shell

Inside tmux, commands are given with key combinations: first the prefix Ctrl+b, release it, then a key. Below this is written as C-b d — "Ctrl+b, then d".

Targets (-t) are written as session:window.pane: work, work:1, work:logs.0. Windows and panes are numbered from 0.

Sessions

CommandWhat it does
tmux new -s namea new named session (full form — new-session)
tmux new -d -s namecreate in the background without attaching
tmux new -d -s name 'command'a session running a command; when it exits, the session closes
tmux new -A -s nameattach if the session exists, otherwise create it
tmux lslist sessions (list-sessions)
tmux attach -t nameattach (a, attach-session); without -t — to the most recent
tmux has-session -t namecode 0 if the session exists — for scripts
tmux rename-session -t old newrename
tmux kill-session -t nameclose a session with all programs in it
tmux kill-serverclose everything

Windows and panes from the command line

CommandWhat it does
tmux new-window -t session -n namea new window
tmux split-window -h / -vsplit a pane: left-right / top-bottom
tmux select-window -t session:nameswitch window
tmux select-pane -t session:0.1switch pane
tmux list-windows -t session / list-paneslist windows / panes
tmux kill-window -t … / kill-pane -t …close a window / pane
tmux send-keys -t target 'text' Enter"type" text into a pane (C-m is also Enter)
tmux capture-pane -p -t targetprint a pane's contents to stdout; -S - — with the whole history
tmux display -p '#S:#I.#P'current session name, window and pane number
tmux source-file ~/.tmux.confreload the config

Keys (after C-b)

KeyAction
ddetach from the session
s / wchoose a session / window from a tree
$rename the session
cnew window
n / p / lnext / previous / last window
0…9window by number
,rename the window
&close the window (with confirmation)
%split the pane into left and right
"split the pane into top and bottom
arrows / omove to the adjacent / next pane
zzoom the pane to the full window and back
xclose the pane (with confirmation)
{ / }swap the pane with its neighbor
Spacenext pane layout
!break the pane out into its own window
qshow pane numbers
[scroll and copy mode; PgUp — enter it already scrolling up
]paste what was copied
:tmux command prompt (kill-session, resize-pane -D 5…)
?list all key bindings

Copy mode

Keys are emacs-style by default. Enter with C-b [, exit with q or Escape. Arrows and PgUp/PgDn scroll the history.

Key (emacs)Key (vi)Action
C-SpaceSpacestart selection
M-wEntercopy and exit
C-s / C-r/ / ?search forward / backward
qqexit

vi keys are enabled in the config: setw -g mode-keys vi.

~/.tmux.conf

LineWhat it does
set -g mouse onmouse: select panes, scroll with the wheel, resize
set -g history-limit 50000pane history length (2000 lines by default)
set -g base-index 1number windows from 1
setw -g mode-keys vivi keys in copy mode
set -g prefix C-a + unbind C-bchange the prefix
bind r source-file ~/.tmux.confC-b r reloads the config

Examples

# put a long command in its own session, detach and come back later
tmux new -s build
#   … start the command, press C-b d …
tmux ls
tmux attach -t build

# start a process in a background session right away
tmux new -d -s worker 'python3 -m http.server 8000'

# attach to an existing session or create one
tmux new -A -s main

# a layout from a script: a window with two panes
tmux new -d -s dev
tmux split-window -h -t dev
tmux send-keys -t dev:0.1 'top' Enter

# see what a pane is printing without attaching
tmux capture-pane -p -t dev:0.0

# does the session exist
tmux has-session -t dev 2>/dev/null && echo "exists"

# close the session
tmux kill-session -t dev

Pitfalls

  • C-b is a prefix, not a command. Press and release Ctrl+b, then the key you need. Holding Ctrl on the second key gives a different combination.
  • % and " get mixed up. % splits into left and right (split-window -h), " — into top and bottom.
  • The mouse wheel doesn't scroll history until set -g mouse on is enabled. Without it — C-b [ and arrows or PgUp.
  • exit in the last pane closes the session rather than detaching. To keep programs running — C-b d.
  • A session created with a command disappears along with the command. tmux new -d -s job 'sleep 1' vanishes from tmux ls after a second.
  • tmux inside tmux: the outer one intercepts the prefix. It reaches the inner one with C-b C-b.
  • attach doesn't work outside a terminal ("open terminal failed: not a terminal"). From scripts, control it with send-keys, capture-pane, has-session.
  • A session lives as long as the tmux server. Rebooting the machine or restarting the container destroys it.
  • After editing ~/.tmux.conf the running server doesn't see the changes — tmux source-file ~/.tmux.conf.

See also

ssh · ps · kill