Starting and attaching sessions 9
| Action | Shortcut |
|---|---|
| Start a new sessionCreates a session with one window and attaches to it; the first one also starts the tmux server. | tmux new |
| Start a named sessionWithout -s, sessions are called 0, 1 and so on in the order they are made. | tmux new -s NAME |
| Attach or create sessionAttaches when a session of that name is already running and creates it otherwise. | tmux new -A -s NAME |
| Attach to latest sessionWith no target, tmux picks the session used last among those that have no client. | tmux attach |
| Attach to a named sessionClients already attached to that session stay connected. | tmux attach -t NAME |
| Attach and detach othersDisconnects every other client from the session while attaching this one. | tmux attach -d -t NAME |
| List sessionsShort for list-sessions; each line shows a session name, its window count and when it was created. | tmux ls |
| Kill a sessionCloses the windows that belong only to that session and detaches its clients; no default key runs it. | tmux kill-session -t NAME |
| Stop tmux entirelyEnds the server with all its sessions; typed after Ctrl + B, : it is kill-server without the word tmux. | tmux kill-server |
Sessions and clients 8
Prefix shortcuts are sequences, not chords: press Ctrl + B, let go, then press the next key. Keeping Ctrl held changes the binding, since tmux treats C-b c and C-b C-c as different keys.
| Action | Shortcut |
|---|---|
| Detach clientThe session and everything running in it stay alive in the background until a client attaches again. | Ctrl+BthenD |
| Choose client to detachOpens client mode, a list of attached clients; Enter detaches the selected one. | Ctrl+BthenShift+D |
| Rename sessionOpens a prompt for the new name of the attached session. | Ctrl+Bthen$ |
| Choose session from treeOpens tree mode showing only sessions, with the attached one selected. | Ctrl+BthenS |
| Previous sessionRuns switch-client -p for the attached client. | Ctrl+Bthen( |
| Next sessionRuns switch-client -n for the attached client. | Ctrl+Bthen) |
| Last sessionReturns the client to the session it was attached to before this one. | Ctrl+BthenShift+L |
| Suspend clientStops the client by sending it SIGTSTP, the terminal stop signal. | Ctrl+BthenCtrl+Z |
Windows 20
The manual writes keys in its own notation: C- stands for Ctrl, M- for Alt (meta) and S- for Shift, so M-n is Alt + N. A capital letter such as D is shown here as Shift + D.
| Action | Shortcut |
|---|---|
| New windowThe window gets the first free index and becomes the current window of the session. | Ctrl+BthenC |
| Kill windowAsks for confirmation, then closes the window together with every pane in it. | Ctrl+Bthen& |
| Rename windowOpens a prompt for the new name of the window you are in. | Ctrl+Bthen, |
| Next windowFollows the window numbers: from window 1 it goes to window 2 when that exists. | Ctrl+BthenN |
| Previous windowGoes to the window one position lower in the numbered window list. | Ctrl+BthenP |
| Last windowReturns to the window that was current before this one. | Ctrl+BthenL |
| Select window by numberEach digit jumps straight to the window that has this index. | Ctrl+Bthen0-9 |
| Select window by indexOpens a prompt; type an index and tmux changes to that window. | Ctrl+Bthen' |
| Choose window from treeOpens tree mode with sessions expanded to their windows and the current window selected. | Ctrl+BthenW |
| Move windowPrompts for the new index; an index that is already taken produces an error. | Ctrl+Bthen. |
| Find windowPrompts for text, then shows only panes whose visible content, title or window name contains it. | Ctrl+BthenF |
| Window infoRuns display-message, which writes its text to the status line. | Ctrl+BthenI |
| Next window with alertSkips windows that carry no bell or activity marker. | Ctrl+BthenAlt+N |
| Previous window with alertSearches backward for the nearest window showing a bell or activity marker. | Ctrl+BthenAlt+P |
| Window menuOpens a menu with entries such as Swap Left, Rename, Kill and New After. | Ctrl+Bthen< |
| Pan window view upMoves the shown area by 10 lines when the window is larger than the terminal of the client. | Ctrl+BthenShift+Up |
| Pan window view down | Ctrl+BthenShift+Down |
| Pan window view leftShifts the shown area by 10 columns per press. | Ctrl+BthenShift+Left |
| Pan window view right | Ctrl+BthenShift+Right |
| Reset window viewGoes back to tracking the cursor after the view was panned. | Ctrl+BthenDelete |
Panes and layouts 22
| Action | Shortcut |
|---|---|
| Split left and rightPuts the new pane to the right of the active one; the command behind it is split-window -h. | Ctrl+Bthen% |
| Split top and bottomPuts the new pane below the active one, using split-window without flags. | Ctrl+Bthen" |
| New floating paneRuns new-pane; the pane floats above the tiled panes of the window. | Ctrl+Bthen* |
| Kill paneAsks for confirmation and closes only the active pane. | Ctrl+BthenX |
| Zoom paneThe pane fills the whole window and hides the others; pressing it again restores the layout. | Ctrl+BthenZ |
| Break pane to windowThe pane leaves its window and becomes the only pane of a new one. | Ctrl+Bthen! |
| Swap with previous paneRuns swap-pane -U, which exchanges the active pane with the one before it. | Ctrl+Bthen{ |
| Swap with next paneRuns swap-pane -D, which exchanges the active pane with the one after it. | Ctrl+Bthen} |
| Rotate panes forwardsRuns rotate-window, which moves every pane on to the next position. | Ctrl+BthenCtrl+O |
| Rotate panes backwardsRuns rotate-window -D, the reverse of Ctrl + B, Ctrl + O. | Ctrl+BthenAlt+O |
| Mark paneToggles the mark; only one pane is marked across all sessions, shown by a green background on its border. | Ctrl+BthenM |
| Clear marked paneAfterwards no pane is marked in any session. | Ctrl+BthenShift+M |
| Next layoutSteps through the preset layouts one after another. | Ctrl+BthenSpace |
| Even-horizontal layoutAll panes sit side by side with equal widths. | Ctrl+BthenAlt+1 |
| Even-vertical layoutAll panes are stacked from top to bottom with equal heights. | Ctrl+BthenAlt+2 |
| Main-horizontal layoutOne large pane on top, the others in a row along the bottom. | Ctrl+BthenAlt+3 |
| Main-vertical layoutOne large pane on the left, the others stacked on the right. | Ctrl+BthenAlt+4 |
| Tiled layoutGives every pane a similar share of the window in a grid of rows and columns. | Ctrl+BthenAlt+5 |
| Main-horizontal-mirrored layoutThe main-horizontal arrangement flipped: the large pane is at the bottom. | Ctrl+BthenAlt+6 |
| Main-vertical-mirrored layoutThe main-vertical arrangement flipped: the large pane is on the right. | Ctrl+BthenAlt+7 |
| Spread panes evenlyRuns select-layout -E on the active pane and the panes next to it. | Ctrl+BthenShift+E |
| Pane menuOpens a menu with entries for the active pane, among them Horizontal Split. | Ctrl+Bthen> |
Moving between panes 7
| Action | Shortcut |
|---|---|
| Next paneGoes to the following pane in pane-number order. | Ctrl+BthenO |
| Last paneReturns to the pane that was active before this one. | Ctrl+Bthen; |
| Select pane aboveWraps around: from a pane at the top it goes to one at the bottom. | Ctrl+BthenUp |
| Select pane belowFrom a pane at the bottom edge it wraps to a pane at the top. | Ctrl+BthenDown |
| Select pane to the leftRepeatable: more arrow presses within the repeat time need no prefix. | Ctrl+BthenLeft |
| Select pane to the right | Ctrl+BthenRight |
| Show pane numbersWhile the numbers are visible, pressing one of them makes that pane active. | Ctrl+BthenQ |
Resizing panes 8
| Action | Shortcut |
|---|---|
| Resize pane up one cellRuns resize-pane -U; the step is a single line. | Ctrl+BthenCtrl+Up |
| Resize pane down one cell | Ctrl+BthenCtrl+Down |
| Resize pane left one cell | Ctrl+BthenCtrl+Left |
| Resize pane right one cellRepeats without the prefix while presses follow within the repeat time, 500 ms by default. | Ctrl+BthenCtrl+Right |
| Resize pane up five cellsRuns resize-pane -U 5 for larger steps. | Ctrl+BthenAlt+Up |
| Resize pane down five cells | Ctrl+BthenAlt+Down |
| Resize pane left five cells | Ctrl+BthenAlt+Left |
| Resize pane right five cells | Ctrl+BthenAlt+Right |
Copy mode and paste buffers 6
The mode-keys option decides which copy mode table applies. Its default is emacs, unless the VISUAL or EDITOR environment variable contains vi when the server starts.
| Action | Shortcut |
|---|---|
| Enter copy modeFreezes the output of the pane so text can be selected and the scrollback read; keys inside need no prefix. | Ctrl+Bthen[ |
| Copy mode, one page upOpens copy mode already moved one page into the scrollback. | Ctrl+BthenPage Up |
| Paste latest bufferInserts the newest paste buffer into the active pane. | Ctrl+Bthen] |
| Choose buffer to pasteOpens buffer mode, a list of buffers with a preview; Enter pastes the selected one. | Ctrl+Bthen= |
| List paste buffersRuns list-buffers, the plain-text counterpart of the chooser on Ctrl + B, =. | Ctrl+Bthen# |
| Delete latest bufferRemoves only the newest buffer; earlier ones remain available. | Ctrl+Bthen- |
Copy mode movement with vi keys 31
The prefix key wins over the keys of a mode. With the default prefix, Ctrl + B inside copy mode is read as the prefix first, so paging up with it takes a second press; Page Up needs one.
| Action | Shortcut |
|---|---|
| Cursor leftLeft, Backspace and Ctrl + H run the same command in this key table. | H |
| Cursor downThe Down arrow runs the same command. | J |
| Cursor upThe Up arrow runs the same command. | K |
| Cursor rightThe Right arrow runs the same command. | L |
| Start of lineHome runs the same command in this key table. | 0 |
| End of lineEnd runs the same command in this key table. | $ |
| Back to indentation | ^ |
| Next wordStops at the start of the following word; the word-separators option sets what divides words. | W |
| End of next word | E |
| Previous wordStops at the start of the word before the cursor. | B |
| Next space-separated wordWorks like W without Shift, but only a space counts as a word separator. | Shift+W |
| End of space-separated word | Shift+E |
| Previous space-separated word | Shift+B |
| Previous paragraph | { |
| Next paragraph | } |
| Matching bracket | % |
| Top line of pane | Shift+H |
| Middle line of pane | Shift+M |
| Bottom line of pane | Shift+L |
| Top of history | G |
| Bottom of history | Shift+G |
| Go to lineOpens a prompt for the line to move to. | : |
| Half page up | Ctrl+U |
| Half page down | Ctrl+D |
| Page upPage Up runs the same command; with the default prefix, Ctrl + B is read as the prefix first. | Ctrl+B |
| Page downPage Down runs the same command in this key table. | Ctrl+F |
| Scroll view upShift + K and Ctrl + Up run the same command. | Ctrl+Y |
| Scroll view downShift + J and Ctrl + Down run the same command. | Ctrl+E |
| Centre current lineThe view scrolls until the line with the cursor sits in the middle. | Z |
| Jump forward before characterStops one character short, just in front of the target. | T |
| Jump backward after character | Shift+T |
Copy mode selection and search with vi keys 10
| Action | Shortcut |
|---|---|
| Begin selectionStart selecting text from the cursor position. | Space |
| Rectangle selectionCtrl + V runs the same command in this key table. | V |
| Select line | Shift+V |
| Go to other end of selection | O |
| Clear selection | Esc |
| Copy selection and exitThe text becomes the newest paste buffer, ready for Ctrl + B, ]. | Enter |
| Append selection and exitAdds the selected text to the top paste buffer rather than making a new buffer. | Shift+A |
| Exit copy modeLeaves without copying; Ctrl + C runs the same command. | Q |
| Search forwardOpens a prompt for the text to find after the cursor. | / |
| Search backwardOpens a prompt for the text to find before the cursor. | ? |
Copy mode movement with emacs keys 26
| Action | Shortcut |
|---|---|
| Cursor upCtrl + P runs the same command. | Up |
| Cursor downCtrl + N runs the same command. | Down |
| Cursor leftCtrl + B is bound to the same command, though the default prefix claims that key first. | Left |
| Cursor rightCtrl + F runs the same command. | Right |
| Start of lineHome is bound to the same command. | Ctrl+A |
| End of lineEnd is bound to the same command. | Ctrl+E |
| Back to indentation | Alt+M |
| End of next word | Alt+F |
| Previous word | Alt+B |
| Previous paragraph | Alt+{ |
| Next paragraph | Alt+} |
| Next matching bracket | Ctrl+Alt+F |
| Previous matching bracket | Ctrl+Alt+B |
| Top line of pane | Alt+Shift+R |
| Middle line of pane | Alt+R |
| Top of history | Alt+< |
| Bottom of history | Alt+> |
| Go to lineOpens a prompt for the line to move to. | G |
| Half page up | Alt+Up |
| Half page down | Alt+Down |
| Page upAlt + V runs the same command. | Page Up |
| Page downCtrl + V and Space run the same command. | Page Down |
| Scroll view up | Ctrl+Up |
| Scroll view down | Ctrl+Down |
| Recentre current lineEach press moves the line with the cursor on: to the centre, then the top, then the bottom. | Ctrl+L |
| Cursor to horizontal centre | Alt+L |
Copy mode selection and search with emacs keys 7
| Action | Shortcut |
|---|---|
| Begin selection | Ctrl+Space |
| Rectangle selection | Shift+R |
| Clear selectionDrops the selection without copying; the same key also stops a search. | Ctrl+G |
| Copy selection and exitCtrl + W copies and leaves copy mode as well. | Alt+W |
| Exit copy modeQ and Ctrl + C run the same command. | Esc |
| Incremental search forwardMatches are found while the search text is being typed. | Ctrl+S |
| Incremental search backward | Ctrl+R |
Command prompt and help 8
| Action | Shortcut |
|---|---|
| Command promptThe prompt replaces the status line; several commands can be joined with a semicolon. | Ctrl+Bthen: |
| List key bindingsShows every key with its description in view mode; Q leaves the list. | Ctrl+Bthen? |
| Describe one keyPrompts for a key press and prints the description of that key. | Ctrl+Bthen/ |
| Send prefix to programPasses a single Ctrl + B to the program in the active pane. | Ctrl+BthenCtrl+B |
| Customize optionsOpens customize mode: a list for looking through options and key bindings and editing them. | Ctrl+BthenShift+C |
| Show clockRuns clock-mode in the active pane. | Ctrl+BthenT |
| Redraw clientRuns refresh-client to repaint the attached terminal. | Ctrl+BthenR |
| Show messagesRuns show-messages, the log of earlier messages kept by the server. | Ctrl+Bthen~ |
Configuration commands 10
| Action | Shortcut |
|---|---|
| Reload the configuration filetmux runs the file only when the server starts; this runs it again, as :source ~/.tmux.conf does at the command prompt. | tmux source-file ~/.tmux.conf |
| Change the prefix keyA line for ~/.tmux.conf; the prefix is an option, so every prefix shortcut then starts with Ctrl + A. | set -g prefix C-a |
| Remove old prefix bindingSecond line of the prefix change: it frees the key that used to send the prefix. | unbind C-b |
| Bind new prefix pass-throughThird line of the prefix change: pressing the new prefix twice passes it to the program. | bind C-a send-prefix |
| Turn mouse support onThe mouse can then pick panes and windows, drag pane borders, copy text and open menus. | set -g mouse on |
| Use vi keys in copy modeCopy mode then reads the copy-mode-vi key table instead of copy-mode. | set -g mode-keys vi |
| Use vi keys at the promptThe option behind it sets the key bindings of the command prompt. | set -g status-keys vi |
| List keys with descriptionsThe shell form of Ctrl + B, ?; lsk is the alias of list-keys. | tmux lsk -N |
| List one key tablePrints the table as bind-key commands; copy-mode and copy-mode-vi are the names of the copy mode tables. | tmux lsk -Tprefix |
| Show global session optionsWith -s it prints the server options and with -wg the global window options. | tmux show -g |
No row on this page matches that filter.
Notes
Sessions: the reason to use tmux at all
Start work in a session, detach with Ctrl + B, D, close the laptop, and reattach later with tmux attach to find every shell exactly where it was. Ctrl + B, $ renames the session to something you will recognise in a week, Ctrl + B, S opens a picker to switch between sessions, and Ctrl + B, ( and Ctrl + B, ) cycle through them. Running a long job inside a session is the habit that ends "the connection dropped and the build died".
Windows and panes
Ctrl + B, C creates a window (a tab), Ctrl + B, N and Ctrl + B, P move between them, and Ctrl + B, 0-9 jumps by number; Ctrl + B, , renames the current one. Within a window, Ctrl + B, % splits into left and right panes and Ctrl + B, " into top and bottom. Ctrl + B, Up, Ctrl + B, Down, Ctrl + B, Left and Ctrl + B, Right move focus by direction, Ctrl + B, Z zooms a pane to fill the window and back, and Ctrl + B, X kills the pane. Ctrl + B, ! promotes a pane to its own window when a split has outgrown its space.
Scrolling and copying
tmux keeps its own scrollback for every pane. Enter copy mode with Ctrl + B, [, or with Ctrl + B, Page Up to start one page up; the keys that work there depend on the mode-keys option. tmux uses emacs keys unless VISUAL or EDITOR contains vi, and set -g mode-keys vi in ~/.tmux.conf selects the vi table. With vi keys, Ctrl + U and Ctrl + D move by half pages, / and ? search, Space begins a selection, Enter copies it and leaves copy mode, and Q exits without copying. With emacs keys the same steps are Alt + Up and Alt + Down, Ctrl + S and Ctrl + R, Ctrl + Space, Alt + W and Esc. Ctrl + B, ] pastes the copied text.
When you forget a key
Ctrl + B, ? lists every binding in the running tmux, including any you have customised, and Ctrl + B, / describes a single key. Ctrl + B, : opens a command prompt where any tmux command can be typed without the leading tmux — kill-session, resize-pane -L 10, source-file ~/.tmux.conf. If the display becomes garbled, Ctrl + B, R redraws it.
Questions
What is the tmux prefix and can I change it?
The prefix is Ctrl + B by default. To move it to Ctrl + A, put set -g prefix C-a, unbind C-b and bind C-a send-prefix in ~/.tmux.conf; every prefix shortcut here then starts with that key instead.
How do I scroll up in tmux?
Enter copy mode with Ctrl + B, [ (or Ctrl + B, Page Up to start one page up) and use the arrow keys or Page Up; Q leaves with vi keys, Esc or Q with emacs keys. With set -g mouse on in ~/.tmux.conf the wheel scrolls a pane directly.
What is the difference between a window and a pane?
A window normally takes up the whole terminal and appears in the window list of the status line; a pane is a split inside a window. Ctrl + B, C makes a window, Ctrl + B, % or Ctrl + B, " makes a pane.
How do I get back to a detached session?
Run tmux attach, or tmux attach -t NAME if there is more than one session. tmux ls lists them.
Why does Ctrl + B not page up in copy mode with vi keys?
Because the prefix key takes precedence over copy mode keys, the first Ctrl + B is read as the prefix. Press it a second time, which sends the key through to copy mode, or use Page Up or Ctrl + U.
How do I detach from a tmux session?
Press Ctrl + B, D: hold Ctrl and press B (the default prefix), release, then press D. Only your client detaches. The session keeps running in the background with everything in it, and it survives a dropped SSH connection in the same way.
To return, run tmux attach in any terminal, or tmux attach -t followed by the session name when there are several; tmux ls lists them. Ctrl + B, Shift + D shows a list of attached clients so that you can choose which one to detach.
How do I zoom a tmux pane to full screen?
Press Ctrl + B, Z (the prefix, then Z). The active pane is zoomed to occupy the whole window; the same sequence again puts it back in its place in the layout.
While a pane is zoomed, tmux appends a Z flag to the window name in the status line, which explains at a glance why the other panes are out of sight. For a pane that should keep a full window for good, Ctrl + B, ! breaks it out into a window of its own.
Sources and checks
- tmux(1) manual page of tmux 3.7c — tmux.1 at release tag 3.7c in the tmux/tmux repository Default prefix keys, copy mode keys for vi and emacs, command synopses
- tmux wiki — Getting Started Shell and configuration command lines, behaviour notes
- tmux 3.7c source code — key-bindings.c (default key bindings) Prefix keys the manual list leaves out: layouts Alt + 1 to 7, menus, view panning, key description, customize mode
- tmux 3.7c source code — server-client.c (key handling) Precedence of the prefix key over mode keys
Every row on this page was matched to a line in the documentation above on . A binding that could not be found there is not listed.
Found a wrong or missing key? Tell us and it gets checked against the source. How we verify describes the process and its limits.