man tmux: the tmux(1) manual explained, section by section

The structure of tmux(1): every section at a glance

Tiles are in the order they appear in the man page and sized by length. Select one to see what it covers, how to jump to it, how much it grew since tmux 3.4, and where this site explains it.

Word counts: tmux.1 from the 3.4 and 3.8 git tags, rendered with mandoc -T utf8 -O width=100 and counted per section. Summaries are ours.

How to find answers in man tmux faster

The man page is long, but tmux can answer most questions about itself directly. These commands show what your server is doing, which is often more useful than the page:

NAME and SYNOPSIS

tmux [-2CDhlNuVv] [-c shell-command] [-f file] [-L socket-name] [-S socket-path] [-T features]
     [command [flags]]

Read it like this: letters in the first bracket are flags that take no value, the following brackets are flags that take one, and everything after them is a tmux command with its own flags. tmux on its own runs default-client-command (new in 3.6, default new-session); tmux ls runs list-sessions; tmux -L work attach -t api combines a global flag with a command. tmux 3.8 adds -h to print this usage (tmux 3.4 rejects it with unknown option -- h).

Client, server and socket: the model behind the manual

The DESCRIPTION section opens with the idea everything else builds on. One server process holds every session, window and pane. Each tmux command you type starts a short-lived client that connects to the server through a Unix socket, sends a command, and either exits (tmux ls) or stays attached and draws the session in your terminal (tmux attach). Detaching only ends the client, which is why programs keep running.

The default socket is /tmp/tmux-UID/default, where UID is your numeric user ID (id -u), so /tmp/tmux-1000/default for most single-user Linux systems and /tmp/tmux-501/default on macOS. $TMUX_TMPDIR replaces /tmp. The tmux-UID directory must not be readable by other users, and if the socket file is deleted while the server runs, kill -USR1 on the server recreates it (we tested this on 3.8). Inside tmux, #{socket_path} shows the socket in use.

DESCRIPTION: sessions, windows and panes

A session is a collection of windows; a window fills the terminal and is split into panes, each a separate pseudo-terminal running its own program. Any number of clients can attach to the same session, and a window can be linked into several sessions at once. When all sessions are gone, the server exits (unless exit-empty is off). Every object has a unique ID you can use in targets and formats: sessions start with $, windows with @ and panes with %:

$ tmux display -p '#{session_id} #{window_id} #{pane_id}'
$0 @0 %0

Targets, the -t argument most commands take, are described in the COMMANDS section: -t work:2.1 is pane 1 of window 2 in session work. The commands reference explains target syntax →

Command-line flags

# A separate test server that does not touch your normal sessions
$ tmux -L test -f /dev/null new -s sandbox
$ tmux -L test kill-server

# A socket at a fixed path, shared with a group (tmux 3.3+ also needs server-access)
$ tmux -S /var/tmux/pair new -d -s pair
$ chgrp devteam /var/tmux/pair && chmod g+rw /var/tmux/pair
$ tmux -S /var/tmux/pair server-access -a alice     # -ar: read-only
$ tmux -S /var/tmux/pair attach -t pair             # what alice runs

Pair programming in depth: sharing a tmux session.

The core commands (CLIENTS AND SESSIONS)

The man page lists commands by area, each with its alias in parentheses. These are the ones you will use daily; the commands reference covers all 92.

DEFAULT KEY BINDINGS and KEY BINDINGS

Two sections cover keys. DEFAULT KEY BINDINGS lists what the prefix (prefix means Ctrl+b) does out of the box; KEY BINDINGS explains bind-key, key tables and key names. Every key belongs to a table: prefix (after the prefix), root (no prefix, bind -n), and copy-mode / copy-mode-vi. The ones to know first:

• Ctrl+b c new window, Ctrl+b % and Ctrl+b " split, Ctrl+b d detach, Ctrl+b [ copy mode, Ctrl+b : command prompt, Ctrl+b ? list keys.
• New in tmux 3.8: Ctrl+b Tab and Ctrl+b Shift+Tab (fuzzy window and session switcher), Ctrl+b @ (float or tile a pane), Ctrl+b T (pane title), Ctrl+b g (move and resize floating panes). Ctrl+b * (new floating pane) arrived in 3.7.

# bind-key [-nr] [-T key-table] [-N note] key command
bind -N "Reload config" r source-file ~/.tmux.conf \; display "Reloaded"
bind -n M-Left select-pane -L        # root table: no prefix
bind -r H resize-pane -L 5           # -r: repeatable without the prefix

Every default key, printable: the cheat sheet.

OPTIONS: server, session, window and pane

Options come in four scopes: server (set -s), session (no flag), window (set -w) and pane (set -p). -g sets the global value that every session or window inherits unless it has its own. tmux works out the scope from the option name, so set -g mouse on is enough in a config file. Options whose names start with @ are user options that tmux stores but does not use, which is how plugins are configured. Some options are arrays: set -as terminal-features ',xterm*:RGB' appends an element.

set -g default-terminal "tmux-256color"
set -as terminal-features ",xterm*:RGB"   # 24-bit color in the outer terminal
set -g history-limit 50000                # default 2000 lines
set -g base-index 1                       # windows start at 1
setw -g pane-base-index 1
set -g renumber-windows on
# Already defaults in 3.8: mouse on, escape-time 10, theme detect

Check a value with tmux show -gv history-limitCopy; in 3.8, show -F takes a format, for example tmux show -g -F '#{option_name}=#{option_value}' history-limit prints history-limit=2000. Every option with its 3.8 default: the config reference.

FORMATS: #{variables}, conditionals and modifiers

A format is a string in which #{name} is replaced by a value: the session name, the pane's directory, whether the prefix is pressed. Formats are used in the status line, in -F arguments to list commands, in display -p, and in hooks. Short aliases exist for the common ones: #S session name, #I window index, #W window name, #P pane index, #H hostname. All of these were checked on tmux 3.8:

# Show PREFIX in yellow while the prefix key is active
set -g status-left "#{?client_prefix,#[bg=yellow]#[fg=black] PREFIX #[default],#[bg=blue]#[fg=white] TMUX #[default]} [#S] "
# Mark the zoomed window with [Z]
set -g window-status-current-format "#I:#W#{?window_zoomed_flag, [Z],}"

The full variable list is in the man page (search for session_id), or run tmux display -aCopy to see every variable with its current value. Formats in list commands make scripting easy: tmux ls -F '#{session_name} #{session_windows}'. New in 3.8: #{A/count:frames} for status-line animations, and colors in styles are expanded as formats. Formats in scripts →

HOOKS: run commands on events

A hook runs tmux commands when something happens. Most commands have an after- hook (after-split-window), and there are event hooks such as client-attached, pane-exited and session-created. Hooks are array options, so one event can run several commands:

# Tile panes evenly after every split
set-hook -g after-split-window "select-layout tiled"
# Show a message when a client attaches
set-hook -g client-attached 'display-message -d 3000 "Client attached: #{client_tty}"'
# Log failed tmux commands
set-hook -g command-error "run-shell \"echo 'tmux command failed' >> /tmp/tmux-errors.log\""
# List every hook and what it runs
show-hooks -g

BUFFERS and the clipboard

Each copy in copy mode creates a paste buffer; tmux keeps the most recent ones (buffer-limit, default 50). The BUFFERS section covers the commands that manage them:

• tmux list-buffers (lsb) lists them, tmux show-buffer prints the newest, tmux save-buffer file.txt writes it to a file.
• Ctrl+b ] pastes the newest buffer, Ctrl+b = picks one from a list, paste-buffer -p pastes with bracketed-paste markers.
• set -s set-clipboard controls OSC 52: with the default external, copying in tmux also sets your terminal's clipboard, even over SSH, if the terminal allows it.

Buffers and the system clipboard are explained step by step in the copy mode guide.

FILES and ENVIRONMENT

What changed in the tmux 3.8 man page

The page grew by more than 3,000 words between 3.7 and 3.8, the biggest jump of any release since 3.0. Most of it is in these sections:

One change affects scripts and plugins: layout strings (#{window_layout}) now use a JSON-like format that includes floating panes. tmux 3.8 still accepts the old format, but older versions cannot read the new one. The full list of changes in plain language is on the releases page.

FAQ

Next steps