tmux cheat sheet: sessions, windows, panes and copy mode

How to read tmux key bindings

Every default keyboard shortcut in tmux starts with the prefix Ctrl-b: press Ctrl-b, let go of both keys, then press the next key. If you get stuck, Ctrl-b ? lists all bindings and Ctrl-b : opens the tmux command prompt. Every command also runs straight from your shell as tmux <command>.

The table lists the key and the shell command for each action, tested on tmux 3.8 and 3.5a.

Sessions

To start a named session, run tmux new -s NAME, or tmux new -A -s NAME to attach to NAME if it is already there and create it if it is not. tmux ls lists what is running and tmux attach -t NAME puts you back inside.

ls, new and attach are official aliases for list-sessions, new-session and attach-session. tmux also accepts any unambiguous prefix of a command name, which is why tmux a works for attach.

Inside a session, Ctrl-b d detaches and leaves everything running. When you are done, tmux kill-session -t NAME ends just that one and tmux kill-server ends all of them at once. The full workflow for long jobs is in the tmux detach and attach guide.

Windows and panes

Windows act like tabs inside a session: Ctrl-b c creates one, Ctrl-b , renames it and Ctrl-b & kills it after asking for confirmation. Ctrl-b n and Ctrl-b p move to the next and previous window, and Ctrl-b w lets you pick from a tree.

Panes split a single window into several terminals. Ctrl-b % splits it left and right, Ctrl-b " splits it top and bottom, and Ctrl-b x kills the active pane after asking first.

If a pane needs more room, Ctrl-b z zooms it to fill the whole window and zooms it back when you press it again. Ctrl-b ! breaks the pane out into its own window.

Copy mode and scrollback

Press Ctrl-b [ to enter copy mode, or Ctrl-b PgUp to enter it and scroll up one page right away; q leaves. The keys default to emacs style (Ctrl-Space starts a selection, Alt-w copies, Ctrl-s and Ctrl-r search) unless $VISUAL or $EDITOR contains "vi". Then you get vi style: Space starts a selection, Enter copies, / and ? search.

Once you have copied something, Ctrl-b ] pastes it into the pane. To dump a pane's whole scrollback to a file from the shell, run tmux capture-pane -p -S - > pane.txt. Every copy mode key is in the tmux scroll and copy mode guide.

Mouse support is on by default since tmux 3.8, so the wheel scrolls back through history, dragging selects and copies text, and clicking selects a pane. Your server might be older, since distribution packages lag behind: Debian 13 ships tmux 3.5a. Check with tmux -V and add set -g mouse on on 3.7 or older.

A starter ~/.tmux.conf

tmux reads ~/.tmux.conf or ~/.config/tmux/tmux.conf once, when the server starts. Reload it into a running server at any time with tmux source-file ~/.tmux.conf.

The default history-limit is 2,000 lines per pane. Since tmux 3.7, raising it also applies to panes that already exist, not only new ones. This config loads without errors on tmux 3.8 and 3.5a:

# Mouse is on by default since tmux 3.8; this line is for older versions
set -g mouse on
set -g history-limit 50000
set -g base-index 1
setw -g pane-base-index 1
set -g mode-keys vi
bind -T copy-mode-vi v send -X begin-selection
bind -T copy-mode-vi y send -X copy-selection-and-cancel
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"

With it, windows and panes count from 1, Ctrl-b | and Ctrl-b - split in the current directory, v and y select and copy like in vim, and Ctrl-b r reloads the file.

Keep a long job running after you log out

tmux new -d -s NAME 'command' starts a job without entering the session, but the session closes as soon as the command exits, taking the final output with it. Start a shell session and type the command into it instead, so the last lines stay readable:

tmux new -d -s train
tmux send-keys -t train 'python -u train.py' Enter
tmux ls
tmux attach -t train

Detaching keeps the process alive, but you still have to SSH back in and reattach every time you want to know whether the job finished or stalled.

Pass environment variables with tmux new -e NAME=value: a tmux server that is already running does not see variables you export later.