tmux Quick Reference

Keep sessions alive across disconnects and split your terminal like a pro. Everything is prefix (Ctrl-b) then a key.

tmux is a terminal multiplexer: a server process owns your shells, and the terminal window you look at is just a client attached to it. Close the terminal or drop the SSH connection and the server keeps everything running, so you can reattach later from anywhere.

It nests sessions (one per project) holding windows (tabs) split into panes. Every shortcut is the prefix — Ctrl-b by default — released, then one key: prefix d means press Ctrl-b, let go, press d. prefix ? lists every binding.

Sessions (survive disconnect)

New named session: tmux new -s work
Detach: prefix d — session keeps running
List / attach: tmux ls · tmux attach -t work
Kill session: tmux kill-session -t work
Rename: prefix $
tmux new -A -s work: attach if work exists, create it if not — one command for every login
tmux new -d -s build 'make all': start a detached session running a command; its window closes when the command exits
tmux attach -d -t work: attach and detach every other client, such as a forgotten one on another machine
prefix s: interactive tree of sessions and windows — arrows to pick, Enter to switch
prefix ( / prefix ): previous / next session; prefix L jumps back to the last one
tmux kill-server: end every session at once, and every program running inside them

Windows (tabs)

New / next / prev: prefix c · prefix n · prefix p
Jump to number: prefix 0..9
Rename window: prefix ,
List windows: prefix w
prefix l: toggle to the last window you were in
prefix &: kill the window and every pane in it (asks to confirm)
prefix .: move the window to another index — renumber your tabs
prefix f: find a window by text shown in any of its panes
tmux new-window -n logs: scriptable new window with a name; -c dir sets its working directory

Panes (split)

Split vertical / horizontal: prefix % (left/right) · prefix " (top/bottom)
Move between panes: prefix then arrow keys · or prefix o
Zoom a pane: prefix z — toggle fullscreen
Close pane: prefix x · or just exit
Cycle layouts: prefix Space
prefix q: flash pane numbers — press a number while they show to jump there
prefix ;: back to the previously active pane
prefix { / prefix }: swap the current pane with the previous / next one
prefix !: break the pane out into a window of its own
prefix Ctrl-arrow: resize the pane by one cell; prefix Alt-arrow resizes by five
prefix Alt-1 … Alt-5: preset layouts: even horizontal, even vertical, main horizontal, main vertical, tiled
setw synchronize-panes on: type into every pane of the window at once — same command on many servers

Copy mode

Enter scroll/copy: prefix [ — then move; q to exit
prefix PgUp: enter copy mode and scroll up a page in one step
Space … Enter: vi keys: start a selection, then copy it and leave copy mode
Ctrl-Space … Alt-w: the same in emacs keys, which are the default
/ and ?: search forward / backward in vi mode (n repeats); emacs mode uses Ctrl-s / Ctrl-r
prefix ]: paste the most recent copy; prefix = picks from older buffers
mode-keys default: emacs, unless $EDITOR or $VISUAL contains “vi” — then vi

Config (~/.tmux.conf)

Reload config: prefix : then source-file ~/.tmux.conf
Common tweak: set -g mouse on for click-to-select panes, drag-to-resize and scrolling
set -g prefix C-a: move the prefix to Ctrl-a; also unbind C-b and bind C-a send-prefix
set -g base-index 1: number windows from 1, matching the keyboard; setw -g pane-base-index 1 for panes
set -g history-limit 50000: scrollback lines per pane (default 2000); applies to panes created afterwards
setw -g mode-keys vi: vi keys in copy mode, whatever $EDITOR says
set -sg escape-time 10: shorter wait after Esc — stops the lag vim users notice
set -g renumber-windows on: close window 2 of 4 and the rest renumber with no gap
set -g default-terminal "tmux-256color": full color and italics; use screen-256color where that terminfo entry is missing

Scripting & misc

tmux send-keys -t work:1 'make' Enter: type into a pane from a script; Enter presses Return
tmux capture-pane -p -S -1000: print the last 1,000 lines of a pane’s scrollback to stdout
tmux pipe-pane -o 'cat >> pane.log': log everything a pane prints from now on; run it again to stop
tmux display -p '#S:#I.#P': print the current session:window.pane — handy in scripts and prompts
prefix prefix: send the prefix through to a tmux nested inside (e.g. over SSH)
prefix :: command prompt: any tmux command, tab-completed
prefix ~: recent tmux messages — where config errors show up

Recipes

Keep a long job running after you disconnect

ssh server
tmux new -A -s deploy          # attach if it exists, create it if not
./long-migration.sh            # start the work
# press prefix d to detach, then log out: the job keeps running

ssh server
tmux attach -t deploy          # back exactly where you left it

The session lives as long as the tmux server process — a reboot still ends it. new -A makes the same command safe to run on every login.

A config that fixes the defaults

# ~/.tmux.conf
set -g prefix C-a              # easier to reach than C-b
unbind C-b
bind C-a send-prefix           # press C-a twice to send it to the program
set -g mouse on                # click panes, drag borders, scroll
set -g base-index 1            # windows start at 1, like the keyboard
setw -g pane-base-index 1
set -g renumber-windows on     # no gaps after closing a window
set -g history-limit 50000     # scrollback per pane
setw -g mode-keys vi           # vi keys in copy mode
set -sg escape-time 10         # no lag after Esc in vim
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
bind r source-file ~/.tmux.conf \; display "config reloaded"

The two bind lines split into the current pane’s directory instead of the session’s start directory. Reload with prefix r; options like history-limit only affect panes created afterwards.

Copy text from the scrollback (vi keys)

prefix [        # enter copy mode
?error          # search backward for "error"; n jumps to the next match
Space           # start the selection at the cursor
j j $           # extend it with vi motions
Enter           # copy the selection and leave copy mode
prefix ]        # paste it into the current pane

With the mouse on, dragging selects and copies too. Hold Shift (Option in iTerm2) to bypass tmux and use the terminal’s own selection — usually the quickest route to the system clipboard.

Script a development layout

tmux new -d -s dev -n editor                  # detached session, first window "editor"
tmux send-keys -t dev:editor 'vim .' Enter
tmux new-window -t dev -n server
tmux send-keys -t dev:server 'npm run dev' Enter
tmux split-window -h -t dev:server            # new pane beside the server
tmux send-keys -t dev:server 'npm test -- --watch' Enter
tmux attach -t dev

Targets read session:window.pane, and names work in place of numbers. Without a .pane part, keys go to the window’s active pane — right after split-window, that is the new one.

Save a pane’s output to a file

tmux capture-pane -p -J -S -10000 > pane.txt   # last 10,000 lines, wrapped lines joined
tmux pipe-pane -o 'cat >> ~/session.log'        # log everything from now on; repeat to stop

capture-pane can only return what is still in scrollback, so raise history-limit before you need it. -S - starts from the very beginning of the history.

Questions about tmux Cheat Sheet

How do I scroll up in tmux?

tmux draws the screen itself, so your terminal’s own scrollbar only sees the current view. Press the prefix and then the left bracket key to enter copy mode, then scroll with the arrow keys, Page Up and Page Down, or Ctrl-b and Ctrl-f with vi keys; prefix then Page Up enters copy mode and scrolls in one step. Press q to return to normal. For mouse-wheel scrolling, add set -g mouse on to your tmux.conf. How far back you can go is set by history-limit, which defaults to 2000 lines per pane.

How do I detach and reattach a tmux session?

Press the prefix and then d to detach: the session and every program in it keep running in the background, even if you close the terminal or your SSH connection drops. Later, run tmux ls to see the running sessions and tmux attach -t name to reconnect, or just tmux attach for the most recent one. tmux new -A -s name attaches when the session exists and creates it otherwise, which makes a good login habit. If another client is attached and the window looks shrunk, attach with -d to detach the others.

What is the difference between tmux sessions, windows and panes?

They nest. A session is the top level, usually one per project or task, and it is what you detach from and reattach to. Each session holds one or more windows, which behave like tabs: only one is visible at a time, and the status bar lists them. Each window can be split into panes, rectangles that are all visible at once and each run their own shell. A typical setup is one session per project, a window each for the editor, the server and the logs, and panes inside a window for things you want to watch side by side.

How do I change the tmux prefix to Ctrl-a?

Add three lines to ~/.tmux.conf: set -g prefix C-a to make Ctrl-a the prefix, unbind C-b to free the old one, and bind C-a send-prefix so pressing Ctrl-a twice still sends a literal Ctrl-a to the program inside, which matters because the shell uses it to jump to the start of the line. Then reload with tmux source-file ~/.tmux.conf, or restart tmux. Ctrl-a is the habit of former GNU screen users; others prefer Ctrl-Space, because it collides with nothing in the shell.

Go deeper

Vim cheatsheet →Bash cheatsheet →