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
| Command | What it does |
|---|---|
tmux new -s name | a new named session (full form — new-session) |
tmux new -d -s name | create 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 name | attach if the session exists, otherwise create it |
tmux ls | list sessions (list-sessions) |
tmux attach -t name | attach (a, attach-session); without -t — to the most recent |
tmux has-session -t name | code 0 if the session exists — for scripts |
tmux rename-session -t old new | rename |
tmux kill-session -t name | close a session with all programs in it |
tmux kill-server | close everything |
Windows and panes from the command line
| Command | What it does |
|---|---|
tmux new-window -t session -n name | a new window |
tmux split-window -h / -v | split a pane: left-right / top-bottom |
tmux select-window -t session:name | switch window |
tmux select-pane -t session:0.1 | switch pane |
tmux list-windows -t session / list-panes | list 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 target | print 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.conf | reload the config |
Keys (after C-b)
| Key | Action |
|---|---|
d | detach from the session |
s / w | choose a session / window from a tree |
$ | rename the session |
c | new window |
n / p / l | next / previous / last window |
0…9 | window 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 / o | move to the adjacent / next pane |
z | zoom the pane to the full window and back |
x | close the pane (with confirmation) |
{ / } | swap the pane with its neighbor |
Space | next pane layout |
! | break the pane out into its own window |
q | show 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-Space | Space | start selection |
M-w | Enter | copy and exit |
C-s / C-r | / / ? | search forward / backward |
q | q | exit |
vi keys are enabled in the config: setw -g mode-keys vi.
~/.tmux.conf
| Line | What it does |
|---|---|
set -g mouse on | mouse: select panes, scroll with the wheel, resize |
set -g history-limit 50000 | pane history length (2000 lines by default) |
set -g base-index 1 | number windows from 1 |
setw -g mode-keys vi | vi keys in copy mode |
set -g prefix C-a + unbind C-b | change the prefix |
bind r source-file ~/.tmux.conf | C-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-bis a prefix, not a command. Press and releaseCtrl+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 onis enabled. Without it —C-b [and arrows orPgUp. exitin 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 fromtmux lsafter a second. - tmux inside tmux: the outer one intercepts the prefix. It reaches the inner one with
C-b C-b. attachdoesn't work outside a terminal ("open terminal failed: not a terminal"). From scripts, control it withsend-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.confthe running server doesn't see the changes —tmux source-file ~/.tmux.conf.