tmux

tmux is a terminal multiplexer: persistent sessions, plus windows and split panes inside a single terminal. The snippets below are verified on tmux 3.2a. The prefix key is assumed to be the default C-b unless stated otherwise.

Cookbook

Create or attach a session (idempotent)

tmux new -A -s name

-A makes new-session behave like attach-session when the session already exists, so there is no “duplicate session” error. That makes it the right command for scripts and shell startup files. Add -d to create it detached; note that -d only applies to creation, so when the session already exists the command attaches anyway (and fails without a terminal). For a strict create-if-missing: tmux has-session -t name 2>/dev/null || tmux new -d -s name.

Tip article: How to create or attach to a tmux session in one command?

Start a named session with a window name and directory

tmux new -d -s projet -n edit -c ~/code/projet

Creates the session projet, names its first window edit, and starts it in ~/code/projet. -d keeps it detached so the command is scriptable; attach later with tmux attach -t projet.

Tip article: How to start a named tmux session with a window name and a directory?

Detach, list, and re-attach a session

tmux ls                 # list running sessions
tmux attach -t projet   # re-attach (short: tmux a -t projet)

Press prefix d to detach: the session keeps running in the background. tmux ls shows what is alive, and tmux attach -t name jumps back in. prefix s runs choose-tree -Zs, an interactive session picker zoomed to full screen.

Tip article: How to detach, list, and re-attach a tmux session?

Rename a session or a window

tmux rename-session -t old new   # rename a session
tmux rename-window new           # rename the current window

From the keyboard, prefix $ renames the current session and prefix , renames the current window, both through a prompt. Renaming a window by hand also turns off its automatic rename, so the name you typed sticks.

Tip article: How to rename a tmux session or window?

Manage clients: list, kick out, disconnect

tmux list-clients -t projet     # who is attached (short: lsc)
tmux attach -d -t projet        # attach here and detach every other client
tmux detach-client -a           # detach all clients except the current one
tmux detach-client -t <client>  # detach one specific client

When several terminals are attached to the same session, attach -d grabs it back to where you are and kicks the others off. prefix D runs choose-client -Z, an interactive client picker. attach -x also sends SIGHUP to the parent process of the client it detaches, which closes, for example, the SSH session that started it.

Tip article: How to manage tmux clients (list, kick out, disconnect)?

Switch between sessions without detaching

tmux switch-client -t other   # move the attached client to session 'other'

No need to detach and re-attach: switch-client moves the current client straight to another session, staying inside tmux. From the keyboard, prefix ( and prefix ) walk to the previous and next session, and prefix L toggles back to the last used session. prefix s opens choose-tree -Zs for an interactive picker.

Tip article: How to switch between tmux sessions without detaching?

Kill a session, or the whole server

tmux kill-session -t name      # kill one session
tmux kill-session -a -t keep   # kill ALL sessions except 'keep'
tmux kill-server               # kill everything: all sessions, the server itself

Killing a session terminates every process in it, unlike detaching which keeps it running. The -a flag inverts the target: everything except the named session dies. kill-server takes the whole server down; the next tmux new starts a fresh one.

Tip article: How to kill a tmux session, or the whole server?

Control a nested tmux: send the prefix inward

# ~/.tmux.conf, when your prefix is C-a
bind C-a send-prefix   # double C-a then targets the inner tmux

With two tmux stacked (a local one and another over SSH, for example), the outer tmux catches the prefix. To reach the inner one, you forward the prefix to it (this sends the outer prefix key, so it assumes both levels use the same prefix). By default prefix C-b runs send-prefix, so with the stock C-b prefix you press it twice. Once your prefix is C-a, add bind C-a send-prefix and a double C-a C-a is sent through to the inner session. The simplest alternative is to give the inner tmux a different prefix so the two never collide.

Tip article: How to control a nested tmux session (send the prefix to the inner one)?

Split a window into panes

tmux split-window -h   # panes side by side (left / right)
tmux split-window -v   # panes stacked (top / bottom)

split-window cuts the active pane in two and starts a new shell in the freed half. The flag names are the usual tmux trap: -h (“horizontal”) gives a vertical divider, so the panes sit side by side, while -v stacks them top and bottom. The flag describes the axis of the cut, not the visual layout. From the keyboard, prefix % does split-window -h and prefix " does the vertical split. Add -c "#{pane_current_path}" to open in the current directory, -b to insert before instead of after, and -l 30% to set the new pane’s size.

The -h/-v names are easy to forget, so it is worth rebinding the splits to keys that match the result, | for side by side and - for stacked (see the sample config below).

Tip article: How to split a tmux window into panes?

Navigate between windows

tmux next-window       # go to the next window
tmux previous-window   # go to the previous window
tmux last-window       # toggle with the previously active window

From the keyboard, prefix n and prefix p step to the next and previous window, and they wrap around the ends. prefix l (lowercase L) is the useful one: it toggles back and forth between the current window and the one you were on before, so jumping to a window and back is two keystrokes. It is the window-level twin of prefix ;, which toggles the last active pane.

Tip article: How to navigate between tmux windows?

Reorder windows

tmux swap-window -s 2 -t 4   # exchange windows 2 and 4
tmux move-window -s 2 -t 4   # move window 2 to index 4 (target must be free)

swap-window exchanges two windows, trading only their index numbers, so neither slot needs to be free. On 3.2a the focus stays on the current index (you end up on the swapped-in window); add -d to make it follow the moved window instead, and beware that -d has flipped meaning between tmux versions. move-window slides one window to a new index, but that index must be empty, otherwise tmux refuses with index in use and changes nothing. From the keyboard, prefix . opens a prompt running move-window -t on the current window. To repack the list and remove the gaps left behind, use renumber-windows.

Tip article: How to reorder tmux windows?

Renumber windows to close the gaps

tmux move-window -r          # repack now: indexes become 0, 1, 2, ...
set -g renumber-windows on   # ~/.tmux.conf: repack on every window close

Closing a window in the middle of the list leaves its index empty, so the windows drift to something like 0 3 7. move-window -r renumbers every window in the current session at once to a contiguous range starting at base-index. Setting renumber-windows on in ~/.tmux.conf does the same thing automatically each time a window closes, so the list never grows gaps and prefix 1, prefix 2, … keep landing where you expect.

Tip article: How to renumber tmux windows and close the gaps?

Stop windows from renaming themselves

setw -g automatic-rename off   # ~/.tmux.conf: keep the names you set

By default tmux runs with automatic-rename on, so each window is named after the program in its active pane and the title keeps shifting from sh to vim to node as you work. Renaming a window by hand turns automatic-rename off for that window alone, so the name sticks; setting it off globally does the same for every window. A separate option, allow-rename (off by default on 3.2a), controls whether a program can push its own title through a terminal escape sequence.

Tip article: How to stop tmux from renaming your windows?

Get notified of activity or silence in a window

setw -g monitor-activity on    # ~/.tmux.conf: flag the window on any output
setw -g monitor-silence 30     # flag it after 30 s with no output (0 = off)
set  -g visual-activity on     # also print a status message
set  -g visual-silence on      # same, for the silence monitor

Run a long job in one window, switch away, and tmux highlights that window when something happens. monitor-activity reacts to new output; monitor-silence reacts to output stopping for N seconds, which is the better “the job finished” signal. With visual-activity on tmux also prints a status message instead of only flagging the window; visual-silence is the silence counterpart. A related option, monitor-bell, flags a window when a program rings the terminal bell and is on by default. Defaults on 3.2a: monitor-activity off, monitor-silence 0, visual-activity off, visual-silence off, monitor-bell on.

Tip article: How to get notified of activity or silence in a tmux window?

Move between panes

tmux select-pane -L     # focus the pane to the left (-R right, -U up, -D down)
tmux select-pane -t :.+ # focus the next pane in order, wrapping around

From the keyboard, prefix then an arrow key moves the focus in that direction. The arrow binds are repeatable, so within the repeat timeout you can keep tapping arrows without pressing the prefix again. prefix o cycles to the next pane in order and wraps back to the first. prefix q runs display-panes, which overlays a large number on each pane; type that number to jump straight to it. The overlay stays up for display-panes-time, 1000 ms by default. To bounce back to where you were, prefix ; toggles the last active pane.

Tip article: How to move between tmux panes?

Jump back to the last active pane

tmux last-pane     # toggle focus back to the previously active pane
tmux select-pane -l   # same toggle from the CLI

prefix ; runs last-pane: it toggles focus between the current pane and the one you were on just before, so bouncing to a pane and back costs one prefix ; each way. It is the pane-level twin of prefix l for windows. select-pane -l (lowercase L) does the same thing, and last-pane -Z keeps a zoomed pane zoomed across the toggle.

Tip article: How to jump back to the last active tmux pane?

Zoom a pane to fullscreen

tmux resize-pane -Z   # toggle the active pane to fullscreen and back

prefix z runs resize-pane -Z: the active pane expands to fill the whole window, and prefix z again restores the previous layout. The other panes are only hidden, not closed, and every process keeps running, so this is a temporary “give me room to read this” toggle, not a rearrangement. While a pane is zoomed, window_zoomed_flag is 1 and the status line shows a Z next to the window name. Splitting, swapping panes, or anything that changes the layout unzooms it automatically; switching windows does not, the pane is still zoomed when you come back.

Tip article: How to zoom a tmux pane to fullscreen?

Resize a pane: relative and absolute

tmux resize-pane -L 10        # push the active pane's border 10 columns to the left
tmux resize-pane -R 10        # ... to the right; -U / -D for up / down
tmux resize-pane -x 80 -y 24  # absolute size: 80 columns, 24 rows

Zoom (resize-pane -Z) is the all-or-nothing version; this is the fine-grained one. -L/-R/-U/-D [N] moves the border in that direction by N cells (default 1), and -x/-y set an exact size. A resize only does something when there is a neighbour on that axis to give or take space: two panes side by side cannot change each other’s height, only their width.

From the keyboard, both sets of binds are repeatable (-r), so you can hold the modifier and tap the arrow keys:

prefix C-Up / C-Down / C-Left / C-Right   resize-pane -U/-D/-L/-R   (step 1)
prefix M-Up / M-Down / M-Left / M-Right   resize-pane -U/-D/-L/-R 5 (step 5, Alt)

To rearrange every pane at once instead of nudging one border, change the layout (see below).

Tip article: How to resize a tmux pane?

Select and copy with the mouse

set -g mouse on   # ~/.tmux.conf: off by default

The mouse is off by default. With mouse on, a left-drag enters copy mode and copies the selection into the tmux paste buffer on release; paste it back with prefix ]. That buffer is tmux’s own, not the system clipboard, so another application sees nothing unless you pipe copy mode to a clipboard tool (pbcopy, xclip, wl-copy). To use the terminal’s native selection and clipboard instead, hold Shift while dragging, which bypasses tmux entirely. Turning the mouse on also enables click-to-focus a pane, click a window name to switch, scroll into the scrollback, and drag a border to resize; a right-click on a pane opens a context menu.

Tip article: How to select and copy text with the mouse in tmux?

Number windows and panes from 1

set  -g base-index 1        # ~/.tmux.conf: windows start at 1
setw -g pane-base-index 1   # panes start at 1
set  -g renumber-windows on # keep the list contiguous on close

By default tmux numbers windows and panes from 0, so the first window is prefix 0, at the far end of the number row. base-index (a session option) and pane-base-index (a window option, hence setw) shift the first index to 1, so prefix 1 selects the first window. Both apply only to windows and panes created afterwards, which is why they belong in ~/.tmux.conf. Pair them with renumber-windows on so closing a window repacks the list instead of leaving a gap. One side effect: the first pane becoming 1 changes how a bare number reads as a pane target, so prefer a pane id (%3) or a window.pane form when a target must be unambiguous.

Tip article: How to make tmux number windows and panes from 1?

Target a pane by number: the N vs N.M trap

tmux swap-pane -s 3      # ambiguous: pane 3 of THIS window, or window 3?
tmux swap-pane -s 3.1    # unambiguous: window 3, pane 1
tmux swap-pane -s %7     # unambiguous: pane id, never reinterpreted

Commands that take a pane target, like swap-pane and join-pane, read a bare number with one rule: it is a pane of the current window when a pane with that index exists, and otherwise a window (tmux then acts on that window’s active pane). So -s 3 points at pane 3 of the current window when it has that many panes, but flips to window 3 the moment it does not, and the switch is silent. Qualify the target to stay deterministic: a window.pane form (3.1), a pane id (%7, shown in #{pane_id} and by list-panes), or a window name (build.1). A pane id is the strongest choice because it is stable for the life of the pane and is never re-read as a window.

Tip article: How to target the right tmux pane by number?

A starter ~/.tmux.conf

Config worth keeping in ~/.tmux.conf. This grows along with the cookbook. Reload it without restarting tmux with tmux source-file ~/.tmux.conf, or from inside a session with prefix : then source-file ~/.tmux.conf.

Use C-a as the prefix

unbind C-b
set -g prefix C-a
bind C-a send-prefix   # press C-a twice to drive a nested tmux

C-a matches GNU screen’s prefix and a is easier to reach than b, which is why many setups switch to it. The bind C-a send-prefix line keeps nested sessions usable: a double C-a C-a forwards the prefix to a tmux running inside this one.

Splits on memorable keys

bind | split-window -h   # | is the vertical divider: panes side by side
bind - split-window -v   # - is the horizontal divider: panes stacked

The default prefix % and prefix " still work; these just add keys that match the resulting layout. Append -c "#{pane_current_path}" to either bind to open the new pane in the current pane’s directory.