1TMUX(1) BSD General Commands Manual TMUX(1)
2
4 tmux — terminal multiplexer
5
7 tmux [-2CDlNuVv] [-c shell-command] [-f file] [-L socket-name]
8 [-S socket-path] [-T features] [command [flags]]
9
11 tmux is a terminal multiplexer: it enables a number of terminals to be
12 created, accessed, and controlled from a single screen. tmux may be de‐
13 tached from a screen and continue running in the background, then later
14 reattached.
15 When tmux is started, it creates a new session with a single window and
17 displays it on screen. A status line at the bottom of the screen shows
18 information on the current session and is used to enter interactive com‐
19 mands.
20 A session is a single collection of pseudo terminals under the management
22 of tmux. Each session has one or more windows linked to it. A window
23 occupies the entire screen and may be split into rectangular panes, each
24 of which is a separate pseudo terminal (the pty(4) manual page documents
25 the technical details of pseudo terminals). Any number of tmux instances
26 may connect to the same session, and any number of windows may be present
27 in the same session. Once all sessions are killed, tmux exits.
28 Each session is persistent and will survive accidental disconnection
30 (such as ssh(1) connection timeout) or intentional detaching (with the
31 ‘C-b d’ key strokes). tmux may be reattached using:
32 $ tmux attach
34 In tmux, a session is displayed on screen by a client and all sessions
36 are managed by a single server. The server and each client are separate
37 processes which communicate through a socket in /tmp.
38 The options are as follows:
40 -2 Force tmux to assume the terminal supports 256 colours.
42 This is equivalent to -T 256.
43 -C Start in control mode (see the CONTROL MODE section).
45 Given twice (-CC) disables echo.
46 -c shell-command
48 Execute shell-command using the default shell. If neces‐
49 sary, the tmux server will be started to retrieve the
50 default-shell option. This option is for compatibility
51 with sh(1) when tmux is used as a login shell.
52 -D Do not start the tmux server as a daemon. This also turns
54 the exit-empty option off. With -D, command may not be
55 specified.
56 -f file Specify an alternative configuration file. By default,
58 tmux loads the system configuration file from
59 /etc/tmux.conf, if present, then looks for a user configu‐
60 ration file at ~/.tmux.conf,
61 $XDG_CONFIG_HOME/tmux/tmux.conf or
62 ~/.config/tmux/tmux.conf.
63 The configuration file is a set of tmux commands which are
65 executed in sequence when the server is first started.
66 tmux loads configuration files once when the server process
67 has started. The source-file command may be used to load a
68 file later.
69 tmux shows any error messages from commands in configura‐
71 tion files in the first session created, and continues to
72 process the rest of the configuration file.
73 -L socket-name
75 tmux stores the server socket in a directory under
76 TMUX_TMPDIR or /tmp if it is unset. The default socket is
77 named default. This option allows a different socket name
78 to be specified, allowing several independent tmux servers
79 to be run. Unlike -S a full path is not necessary: the
80 sockets are all created in a directory tmux-UID under the
81 directory given by TMUX_TMPDIR or in /tmp. The tmux-UID
82 directory is created by tmux and must not be world read‐
83 able, writable or executable.
84 If the socket is accidentally removed, the SIGUSR1 signal
86 may be sent to the tmux server process to recreate it (note
87 that this will fail if any parent directories are missing).
88 -l Behave as a login shell. This flag currently has no effect
90 and is for compatibility with other shells when using tmux
91 as a login shell.
92 -N Do not start the server even if the command would normally
94 do so (for example new-session or start-server).
95 -S socket-path
97 Specify a full alternative path to the server socket. If
98 -S is specified, the default socket directory is not used
99 and any -L flag is ignored.
100 -T features Set terminal features for the client. This is a comma-sep‐
102 arated list of features. See the terminal-features option.
103 -u Write UTF-8 output to the terminal even if the first envi‐
105 ronment variable of LC_ALL, LC_CTYPE, or LANG that is set
106 does not contain "UTF-8" or "UTF8".
107 -V Report the tmux version.
109 -v Request verbose logging. Log messages will be saved into
111 tmux-client-PID.log and tmux-server-PID.log files in the
112 current directory, where PID is the PID of the server or
113 client process. If -v is specified twice, an additional
114 tmux-out-PID.log file is generated with a copy of every‐
115 thing tmux writes to the terminal.
116 The SIGUSR2 signal may be sent to the tmux server process
118 to toggle logging between on (as if -v was given) and off.
119 command [flags]
121 This specifies one of a set of commands used to control
122 tmux, as described in the following sections. If no com‐
123 mands are specified, the new-session command is assumed.
124
126 tmux may be controlled from an attached client by using a key combination
127 of a prefix key, ‘C-b’ (Ctrl-b) by default, followed by a command key.
128 The default command key bindings are:
130 C-b Send the prefix key (C-b) through to the application.
132 C-o Rotate the panes in the current window forwards.
133 C-z Suspend the tmux client.
134 ! Break the current pane out of the window.
135 " Split the current pane into two, top and bottom.
136 # List all paste buffers.
137 $ Rename the current session.
138 % Split the current pane into two, left and right.
139 & Kill the current window.
140 ' Prompt for a window index to select.
141 ( Switch the attached client to the previous session.
142 ) Switch the attached client to the next session.
143 , Rename the current window.
144 - Delete the most recently copied buffer of text.
145 . Prompt for an index to move the current window.
146 0 to 9 Select windows 0 to 9.
147 : Enter the tmux command prompt.
148 ; Move to the previously active pane.
149 = Choose which buffer to paste interactively from a list.
150 ? List all key bindings.
151 D Choose a client to detach.
152 L Switch the attached client back to the last session.
153 [ Enter copy mode to copy text or view the history.
154 ] Paste the most recently copied buffer of text.
155 c Create a new window.
156 d Detach the current client.
157 f Prompt to search for text in open windows.
158 i Display some information about the current window.
159 l Move to the previously selected window.
160 m Mark the current pane (see select-pane -m).
161 M Clear the marked pane.
162 n Change to the next window.
163 o Select the next pane in the current window.
164 p Change to the previous window.
165 q Briefly display pane indexes.
166 r Force redraw of the attached client.
167 s Select a new session for the attached client interac‐
168 tively.
169 t Show the time.
170 w Choose the current window interactively.
171 x Kill the current pane.
172 z Toggle zoom state of the current pane.
173 { Swap the current pane with the previous pane.
174 } Swap the current pane with the next pane.
175 ~ Show previous messages from tmux, if any.
176 Page Up Enter copy mode and scroll one page up.
177 Up, Down
178 Left, Right
179 Change to the pane above, below, to the left, or to the
180 right of the current pane.
181 M-1 to M-5 Arrange panes in one of the five preset layouts: even-
182 horizontal, even-vertical, main-horizontal, main-verti‐
183 cal, or tiled.
184 Space Arrange the current window in the next preset layout.
185 M-n Move to the next window with a bell or activity marker.
186 M-o Rotate the panes in the current window backwards.
187 M-p Move to the previous window with a bell or activity
188 marker.
189 C-Up, C-Down
190 C-Left, C-Right
191 Resize the current pane in steps of one cell.
192 M-Up, M-Down
193 M-Left, M-Right
194 Resize the current pane in steps of five cells.
195 Key bindings may be changed with the bind-key and unbind-key commands.
197
199 tmux supports a large number of commands which can be used to control its
200 behaviour. Each command is named and can accept zero or more flags and
201 arguments. They may be bound to a key with the bind-key command or run
202 from the shell prompt, a shell script, a configuration file or the com‐
203 mand prompt. For example, the same set-option command run from the shell
204 prompt, from ~/.tmux.conf and bound to a key may look like:
205 $ tmux set-option -g status-style bg=cyan
207 set-option -g status-style bg=cyan
209 bind-key C set-option -g status-style bg=cyan
211 Here, the command name is ‘set-option’, ‘-g’ is a flag and ‘status-style’
213 and ‘bg=cyan’ are arguments.
214 tmux distinguishes between command parsing and execution. In order to
216 execute a command, tmux needs it to be split up into its name and argu‐
217 ments. This is command parsing. If a command is run from the shell, the
218 shell parses it; from inside tmux or from a configuration file, tmux
219 does. Examples of when tmux parses commands are:
220 - in a configuration file;
222 - typed at the command prompt (see command-prompt);
224 - given to bind-key;
226 - passed as arguments to if-shell or confirm-before.
228 To execute commands, each client has a ‘command queue’. A global command
230 queue not attached to any client is used on startup for configuration
231 files like ~/.tmux.conf. Parsed commands added to the queue are executed
232 in order. Some commands, like if-shell and confirm-before, parse their
233 argument to create a new command which is inserted immediately after
234 themselves. This means that arguments can be parsed twice or more - once
235 when the parent command (such as if-shell) is parsed and again when it
236 parses and executes its command. Commands like if-shell, run-shell and
237 display-panes stop execution of subsequent commands on the queue until
238 something happens - if-shell and run-shell until a shell command finishes
239 and display-panes until a key is pressed. For example, the following
240 commands:
241 new-session; new-window
243 if-shell "true" "split-window"
244 kill-session
245 Will execute new-session, new-window, if-shell, the shell command
247 true(1), split-window and kill-session in that order.
248 The COMMANDS section lists the tmux commands and their arguments.
250
252 This section describes the syntax of commands parsed by tmux, for example
253 in a configuration file or at the command prompt. Note that when com‐
254 mands are entered into the shell, they are parsed by the shell - see for
255 example ksh(1) or csh(1).
256 Each command is terminated by a newline or a semicolon (;). Commands
258 separated by semicolons together form a ‘command sequence’ - if a command
259 in the sequence encounters an error, no subsequent commands are executed.
260 It is recommended that a semicolon used as a command separator should be
262 written as an individual token, for example from sh(1):
263 $ tmux neww \; splitw
265 Or:
267 $ tmux neww ';' splitw
269 Or from the tmux command prompt:
271 neww ; splitw
273 However, a trailing semicolon is also interpreted as a command separator,
275 for example in these sh(1) commands:
276 $ tmux neww\; splitw
278 Or:
280 $ tmux 'neww;' splitw
282 As in these examples, when running tmux from the shell extra care must be
284 taken to properly quote semicolons:
285 1. Semicolons that should be interpreted as a command separator
287 should be escaped according to the shell conventions. For
288 sh(1) this typically means quoted (such as ‘neww ';' splitw’)
289 or escaped (such as ‘neww \\\\; splitw’).
290 2. Individual semicolons or trailing semicolons that should be
292 interpreted as arguments should be escaped twice: once accord‐
293 ing to the shell conventions and a second time for tmux; for
294 example:
295 $ tmux neww 'foo\\;' bar
297 $ tmux neww foo\\\\; bar
298 3. Semicolons that are not individual tokens or trailing another
300 token should only be escaped once according to shell conven‐
301 tions; for example:
302 $ tmux neww 'foo-;-bar'
304 $ tmux neww foo-\\;-bar
305 Comments are marked by the unquoted # character - any remaining text af‐
307 ter a comment is ignored until the end of the line.
308 If the last character of a line is \, the line is joined with the follow‐
310 ing line (the \ and the newline are completely removed). This is called
311 line continuation and applies both inside and outside quoted strings and
312 in comments, but not inside braces.
313 Command arguments may be specified as strings surrounded by single (')
315 quotes, double quotes (") or braces ({}). This is required when the ar‐
316 gument contains any special character. Single and double quoted strings
317 cannot span multiple lines except with line continuation. Braces can
318 span multiple lines.
319 Outside of quotes and inside double quotes, these replacements are per‐
321 formed:
322 - Environment variables preceded by $ are replaced with their
324 value from the global environment (see the GLOBAL AND SESSION
325 ENVIRONMENT section).
326 - A leading ~ or ~user is expanded to the home directory of the
328 current or specified user.
329 - \uXXXX or \uXXXXXXXX is replaced by the Unicode codepoint cor‐
331 responding to the given four or eight digit hexadecimal number.
332 - When preceded (escaped) by a \, the following characters are
334 replaced: \e by the escape character; \r by a carriage return;
335 \n by a newline; and \t by a tab.
336 - \ooo is replaced by a character of the octal value ooo. Three
338 octal digits are required, for example \001. The largest valid
339 character is \377.
340 - Any other characters preceded by \ are replaced by themselves
342 (that is, the \ is removed) and are not treated as having any
343 special meaning - so for example \; will not mark a command se‐
344 quence and \$ will not expand an environment variable.
345 Braces are parsed as a configuration file (so conditions such as ‘%if’
347 are processed) and then converted into a string. They are designed to
348 avoid the need for additional escaping when passing a group of tmux com‐
349 mands as an argument (for example to if-shell). These two examples pro‐
350 duce an identical command - note that no escaping is needed when using
351 {}:
352 if-shell true {
354 display -p 'brace-dollar-foo: }$foo'
355 }
356 if-shell true "display -p 'brace-dollar-foo: }\$foo'"
358 Braces may be enclosed inside braces, for example:
360 bind x if-shell "true" {
362 if-shell "true" {
363 display "true!"
364 }
365 }
366 Environment variables may be set by using the syntax ‘name=value’, for
368 example ‘HOME=/home/user’. Variables set during parsing are added to the
369 global environment. A hidden variable may be set with ‘%hidden’, for ex‐
370 ample:
371 %hidden MYVAR=42
373 Hidden variables are not passed to the environment of processes created
375 by tmux. See the GLOBAL AND SESSION ENVIRONMENT section.
376 Commands may be parsed conditionally by surrounding them with ‘%if’,
378 ‘%elif’, ‘%else’ and ‘%endif’. The argument to ‘%if’ and ‘%elif’ is ex‐
379 panded as a format (see FORMATS) and if it evaluates to false (zero or
380 empty), subsequent text is ignored until the closing ‘%elif’, ‘%else’ or
381 ‘%endif’. For example:
382 %if "#{==:#{host},myhost}"
384 set -g status-style bg=red
385 %elif "#{==:#{host},myotherhost}"
386 set -g status-style bg=green
387 %else
388 set -g status-style bg=blue
389 %endif
390 Will change the status line to red if running on ‘myhost’, green if run‐
392 ning on ‘myotherhost’, or blue if running on another host. Conditionals
393 may be given on one line, for example:
394 %if #{==:#{host},myhost} set -g status-style bg=red %endif
396
398 This section describes the commands supported by tmux. Most commands ac‐
399 cept the optional -t (and sometimes -s) argument with one of
400 target-client, target-session, target-window, or target-pane. These
401 specify the client, session, window or pane which a command should af‐
402 fect.
403 target-client should be the name of the client, typically the pty(4) file
405 to which the client is connected, for example either of /dev/ttyp1 or
406 ttyp1 for the client attached to /dev/ttyp1. If no client is specified,
407 tmux attempts to work out the client currently in use; if that fails, an
408 error is reported. Clients may be listed with the list-clients command.
409 target-session is tried as, in order:
411 1. A session ID prefixed with a $.
413 2. An exact name of a session (as listed by the list-sessions
415 command).
416 3. The start of a session name, for example ‘mysess’ would match
418 a session named ‘mysession’.
419 4. An fnmatch(3) pattern which is matched against the session
421 name.
422 If the session name is prefixed with an ‘=’, only an exact match is ac‐
424 cepted (so ‘=mysess’ will only match exactly ‘mysess’, not ‘mysession’).
425 If a single session is found, it is used as the target session; multiple
427 matches produce an error. If a session is omitted, the current session
428 is used if available; if no current session is available, the most re‐
429 cently used is chosen.
430 target-window (or src-window or dst-window) specifies a window in the
432 form session:window. session follows the same rules as for
433 target-session, and window is looked for in order as:
434 1. A special token, listed below.
436 2. A window index, for example ‘mysession:1’ is window 1 in ses‐
438 sion ‘mysession’.
439 3. A window ID, such as @1.
441 4. An exact window name, such as ‘mysession:mywindow’.
443 5. The start of a window name, such as ‘mysession:mywin’.
445 6. As an fnmatch(3) pattern matched against the window name.
447 Like sessions, a ‘=’ prefix will do an exact match only. An empty window
449 name specifies the next unused index if appropriate (for example the
450 new-window and link-window commands) otherwise the current window in
451 session is chosen.
452 The following special tokens are available to indicate particular win‐
454 dows. Each has a single-character alternative form.
455 Token Meaning
457 {start} ^ The lowest-numbered window
458 {end} $ The highest-numbered window
459 {last} ! The last (previously current) window
460 {next} + The next window by number
461 {previous} - The previous window by number
462 target-pane (or src-pane or dst-pane) may be a pane ID or takes a similar
464 form to target-window but with the optional addition of a period followed
465 by a pane index or pane ID, for example: ‘mysession:mywindow.1’. If the
466 pane index is omitted, the currently active pane in the specified window
467 is used. The following special tokens are available for the pane index:
468 Token Meaning
470 {last} ! The last (previously active) pane
471 {next} + The next pane by number
472 {previous} - The previous pane by number
473 {top} The top pane
474 {bottom} The bottom pane
475 {left} The leftmost pane
476 {right} The rightmost pane
477 {top-left} The top-left pane
478 {top-right} The top-right pane
479 {bottom-left} The bottom-left pane
480 {bottom-right} The bottom-right pane
481 {up-of} The pane above the active pane
482 {down-of} The pane below the active pane
483 {left-of} The pane to the left of the active pane
484 {right-of} The pane to the right of the active pane
485 The tokens ‘+’ and ‘-’ may be followed by an offset, for example:
487 select-window -t:+2
489 In addition, target-session, target-window or target-pane may consist en‐
491 tirely of the token ‘{mouse}’ (alternative form ‘=’) to specify the ses‐
492 sion, window or pane where the most recent mouse event occurred (see the
493 MOUSE SUPPORT section) or ‘{marked}’ (alternative form ‘~’) to specify
494 the marked pane (see select-pane -m).
495 Sessions, window and panes are each numbered with a unique ID; session
497 IDs are prefixed with a ‘$’, windows with a ‘@’, and panes with a ‘%’.
498 These are unique and are unchanged for the life of the session, window or
499 pane in the tmux server. The pane ID is passed to the child process of
500 the pane in the TMUX_PANE environment variable. IDs may be displayed us‐
501 ing the ‘session_id’, ‘window_id’, or ‘pane_id’ formats (see the FORMATS
502 section) and the display-message, list-sessions, list-windows or
503 list-panes commands.
504 shell-command arguments are sh(1) commands. This may be a single argu‐
506 ment passed to the shell, for example:
507 new-window 'vi ~/.tmux.conf'
509 Will run:
511 /bin/sh -c 'vi ~/.tmux.conf'
513 Additionally, the new-window, new-session, split-window, respawn-window
515 and respawn-pane commands allow shell-command to be given as multiple ar‐
516 guments and executed directly (without ‘sh -c’). This can avoid issues
517 with shell quoting. For example:
518 $ tmux new-window vi ~/.tmux.conf
520 Will run vi(1) directly without invoking the shell.
522 command [argument ...] refers to a tmux command, either passed with the
524 command and arguments separately, for example:
525 bind-key F1 set-option status off
527 Or passed as a single string argument in .tmux.conf, for example:
529 bind-key F1 { set-option status off }
531 Example tmux commands include:
533 refresh-client -t/dev/ttyp2
535 rename-session -tfirst newname
537 set-option -wt:0 monitor-activity on
539 new-window ; split-window -d
541 bind-key R source-file ~/.tmux.conf \; \
543 display-message "source-file done"
544 Or from sh(1):
546 $ tmux kill-window -t :1
548 $ tmux new-window \; split-window -d
550 $ tmux new-session -d 'vi ~/.tmux.conf' \; split-window -d \; attach
552
554 The tmux server manages clients, sessions, windows and panes. Clients
555 are attached to sessions to interact with them, either when they are cre‐
556 ated with the new-session command, or later with the attach-session com‐
557 mand. Each session has one or more windows linked into it. Windows may
558 be linked to multiple sessions and are made up of one or more panes, each
559 of which contains a pseudo terminal. Commands for creating, linking and
560 otherwise manipulating windows are covered in the WINDOWS AND PANES sec‐
561 tion.
562 The following commands are available to manage clients and sessions:
564 attach-session [-dErx] [-c working-directory] [-f flags] [-t
566 target-session]
567 (alias: attach)
568 If run from outside tmux, create a new client in the current ter‐
569 minal and attach it to target-session. If used from inside,
570 switch the current client. If -d is specified, any other clients
571 attached to the session are detached. If -x is given, send
572 SIGHUP to the parent process of the client as well as detaching
573 the client, typically causing it to exit. -f sets a comma-sepa‐
574 rated list of client flags. The flags are:
575 active-pane
577 the client has an independent active pane
578 ignore-size
580 the client does not affect the size of other clients
581 no-output
583 the client does not receive pane output in control mode
584 pause-after=seconds
586 output is paused once the pane is seconds behind in con‐
587 trol mode
588 read-only
590 the client is read-only
591 wait-exit
593 wait for an empty line input before exiting in control
594 mode
595 A leading ‘!’ turns a flag off if the client is already attached.
597 -r is an alias for -f read-only,ignore-size. When a client is
598 read-only, only keys bound to the detach-client or switch-client
599 commands have any effect. A client with the active-pane flag al‐
600 lows the active pane to be selected independently of the window's
601 active pane used by clients without the flag. This only affects
602 the cursor position and commands issued from the client; other
603 features such as hooks and styles continue to use the window's
604 active pane.
605 If no server is started, attach-session will attempt to start it;
607 this will fail unless sessions are created in the configuration
608 file.
609 The target-session rules for attach-session are slightly ad‐
611 justed: if tmux needs to select the most recently used session,
612 it will prefer the most recently used unattached session.
613 -c will set the session working directory (used for new windows)
615 to working-directory.
616 If -E is used, the update-environment option will not be applied.
618 detach-client [-aP] [-E shell-command] [-s target-session] [-t
620 target-client]
621 (alias: detach)
622 Detach the current client if bound to a key, the client specified
623 with -t, or all clients currently attached to the session speci‐
624 fied by -s. The -a option kills all but the client given with
625 -t. If -P is given, send SIGHUP to the parent process of the
626 client, typically causing it to exit. With -E, run shell-command
627 to replace the client.
628 has-session [-t target-session]
630 (alias: has)
631 Report an error and exit with 1 if the specified session does not
632 exist. If it does exist, exit with 0.
633 kill-server
635 Kill the tmux server and clients and destroy all sessions.
636 kill-session [-aC] [-t target-session]
638 Destroy the given session, closing any windows linked to it and
639 no other sessions, and detaching all clients attached to it. If
640 -a is given, all sessions but the specified one is killed. The
641 -C flag clears alerts (bell, activity, or silence) in all windows
642 linked to the session.
643 list-clients [-F format] [-f filter] [-t target-session]
645 (alias: lsc)
646 List all clients attached to the server. -F specifies the format
647 of each line and -f a filter. Only clients for which the filter
648 is true are shown. See the FORMATS section. If target-session
649 is specified, list only clients connected to that session.
650 list-commands [-F format] [command]
652 (alias: lscm)
653 List the syntax of command or - if omitted - of all commands sup‐
654 ported by tmux.
655 list-sessions [-F format] [-f filter]
657 (alias: ls)
658 List all sessions managed by the server. -F specifies the format
659 of each line and -f a filter. Only sessions for which the filter
660 is true are shown. See the FORMATS section.
661 lock-client [-t target-client]
663 (alias: lockc)
664 Lock target-client, see the lock-server command.
665 lock-session [-t target-session]
667 (alias: locks)
668 Lock all clients attached to target-session.
669 new-session [-AdDEPX] [-c start-directory] [-e environment] [-f flags]
671 [-F format] [-n window-name] [-s session-name] [-t group-name]
672 [-x width] [-y height] [shell-command]
673 (alias: new)
674 Create a new session with name session-name.
675 The new session is attached to the current terminal unless -d is
677 given. window-name and shell-command are the name of and shell
678 command to execute in the initial window. With -d, the initial
679 size comes from the global default-size option; -x and -y can be
680 used to specify a different size. ‘-’ uses the size of the cur‐
681 rent client if any. If -x or -y is given, the default-size op‐
682 tion is set for the session. -f sets a comma-separated list of
683 client flags (see attach-session).
684 If run from a terminal, any termios(4) special characters are
686 saved and used for new windows in the new session.
687 The -A flag makes new-session behave like attach-session if
689 session-name already exists; if -A is given, -D behaves like -d
690 to attach-session, and -X behaves like -x to attach-session.
691 If -t is given, it specifies a session group. Sessions in the
693 same group share the same set of windows - new windows are linked
694 to all sessions in the group and any windows closed removed from
695 all sessions. The current and previous window and any session
696 options remain independent and any session in a group may be
697 killed without affecting the others. The group-name argument may
698 be:
699 1. the name of an existing group, in which case the new ses‐
701 sion is added to that group;
702 2. the name of an existing session - the new session is
704 added to the same group as that session, creating a new
705 group if necessary;
706 3. the name for a new group containing only the new session.
708 -n and shell-command are invalid if -t is used.
710 The -P option prints information about the new session after it
712 has been created. By default, it uses the format
713 ‘#{session_name}:’ but a different format may be specified with
714 -F.
715 If -E is used, the update-environment option will not be applied.
717 -e takes the form ‘VARIABLE=value’ and sets an environment vari‐
718 able for the newly created session; it may be specified multiple
719 times.
720 refresh-client [-cDLRSU] [-A pane:state] [-B name:what:format] [-C size]
722 [-f flags] [-l [target-pane]] [-t target-client] [adjustment]
723 (alias: refresh)
724 Refresh the current client if bound to a key, or a single client
725 if one is given with -t. If -S is specified, only update the
726 client's status line.
727 The -U, -D, -L -R, and -c flags allow the visible portion of a
729 window which is larger than the client to be changed. -U moves
730 the visible part up by adjustment rows and -D down, -L left by
731 adjustment columns and -R right. -c returns to tracking the cur‐
732 sor automatically. If adjustment is omitted, 1 is used. Note
733 that the visible position is a property of the client not of the
734 window, changing the current window in the attached session will
735 reset it.
736 -C sets the width and height of a control mode client or of a
738 window for a control mode client, size must be one of
739 ‘widthxheight’ or ‘window ID:widthxheight’, for example ‘80x24’
740 or ‘@0:80x24’. -A allows a control mode client to trigger ac‐
741 tions on a pane. The argument is a pane ID (with leading ‘%’), a
742 colon, then one of ‘on’, ‘off’, ‘continue’ or ‘pause’. If ‘off’,
743 tmux will not send output from the pane to the client and if all
744 clients have turned the pane off, will stop reading from the
745 pane. If ‘continue’, tmux will return to sending output to the
746 pane if it was paused (manually or with the pause-after flag).
747 If ‘pause’, tmux will pause the pane. -A may be given multiple
748 times for different panes.
749 -B sets a subscription to a format for a control mode client.
751 The argument is split into three items by colons: name is a name
752 for the subscription; what is a type of item to subscribe to;
753 format is the format. After a subscription is added, changes to
754 the format are reported with the %subscription-changed notifica‐
755 tion, at most once a second. If only the name is given, the sub‐
756 scription is removed. what may be empty to check the format only
757 for the attached session, or one of: a pane ID such as ‘%0’; ‘%*’
758 for all panes in the attached session; a window ID such as ‘@0’;
759 or ‘@*’ for all windows in the attached session.
760 -f sets a comma-separated list of client flags, see
762 attach-session.
763 -l requests the clipboard from the client using the xterm(1) es‐
765 cape sequence. If target-pane is given, the clipboard is sent
766 (in encoded form), otherwise it is stored in a new paste buffer.
767 -L, -R, -U and -D move the visible portion of the window left,
769 right, up or down by adjustment, if the window is larger than the
770 client. -c resets so that the position follows the cursor. See
771 the window-size option.
772 rename-session [-t target-session] new-name
774 (alias: rename)
775 Rename the session to new-name.
776 server-access [-adlrw] [user]
778 Change the access or read/write permission of user. The user
779 running the tmux server (its owner) and the root user cannot be
780 changed and are always permitted access.
781 -a and -d are used to give or revoke access for the specified
783 user. If the user is already attached, the -d flag causes their
784 clients to be detached.
785 -r and -w change the permissions for user: -r makes their clients
787 read-only and -w writable. -l lists current access permissions.
788 By default, the access list is empty and tmux creates sockets
790 with file system permissions preventing access by any user other
791 than the owner (and root). These permissions must be changed
792 manually. Great care should be taken not to allow access to un‐
793 trusted users even read-only.
794 show-messages [-JT] [-t target-client]
796 (alias: showmsgs)
797 Show server messages or information. Messages are stored, up to
798 a maximum of the limit set by the message-limit server option.
799 -J and -T show debugging information about jobs and terminals.
800 source-file [-Fnqv] [-t target-pane] path ...
802 (alias: source)
803 Execute commands from one or more files specified by path (which
804 may be glob(7) patterns). If -F is present, then path is ex‐
805 panded as a format. If -q is given, no error will be returned if
806 path does not exist. With -n, the file is parsed but no commands
807 are executed. -v shows the parsed commands and line numbers if
808 possible.
809 start-server
811 (alias: start)
812 Start the tmux server, if not already running, without creating
813 any sessions.
814 Note that as by default the tmux server will exit with no ses‐
816 sions, this is only useful if a session is created in
817 ~/.tmux.conf, exit-empty is turned off, or another command is run
818 as part of the same command sequence. For example:
819 $ tmux start \; show -g
821 suspend-client [-t target-client]
823 (alias: suspendc)
824 Suspend a client by sending SIGTSTP (tty stop).
825 switch-client [-ElnprZ] [-c target-client] [-t target-session] [-T
827 key-table]
828 (alias: switchc)
829 Switch the current session for client target-client to
830 target-session. As a special case, -t may refer to a pane (a
831 target that contains ‘:’, ‘.’ or ‘%’), to change session, window
832 and pane. In that case, -Z keeps the window zoomed if it was
833 zoomed. If -l, -n or -p is used, the client is moved to the
834 last, next or previous session respectively. -r toggles the
835 client read-only and ignore-size flags (see the attach-session
836 command).
837 If -E is used, update-environment option will not be applied.
839 -T sets the client's key table; the next key from the client will
841 be interpreted from key-table. This may be used to configure
842 multiple prefix keys, or to bind commands to sequences of keys.
843 For example, to make typing ‘abc’ run the list-keys command:
844 bind-key -Ttable2 c list-keys
846 bind-key -Ttable1 b switch-client -Ttable2
847 bind-key -Troot a switch-client -Ttable1
848
850 Each window displayed by tmux may be split into one or more panes; each
851 pane takes up a certain area of the display and is a separate terminal.
852 A window may be split into panes using the split-window command. Windows
853 may be split horizontally (with the -h flag) or vertically. Panes may be
854 resized with the resize-pane command (bound to ‘C-Up’, ‘C-Down’ ‘C-Left’
855 and ‘C-Right’ by default), the current pane may be changed with the
856 select-pane command and the rotate-window and swap-pane commands may be
857 used to swap panes without changing their position. Panes are numbered
858 beginning from zero in the order they are created.
859 By default, a tmux pane permits direct access to the terminal contained
861 in the pane. A pane may also be put into one of several modes:
862 - Copy mode, which permits a section of a window or its history
864 to be copied to a paste buffer for later insertion into another
865 window. This mode is entered with the copy-mode command, bound
866 to ‘[’ by default. Copied text can be pasted with the
867 paste-buffer command, bound to ‘]’.
868 - View mode, which is like copy mode but is entered when a com‐
870 mand that produces output, such as list-keys, is executed from
871 a key binding.
872 - Choose mode, which allows an item to be chosen from a list.
874 This may be a client, a session or window or pane, or a buffer.
875 This mode is entered with the choose-buffer, choose-client and
876 choose-tree commands.
877 In copy mode an indicator is displayed in the top-right corner of the
879 pane with the current position and the number of lines in the history.
880 Commands are sent to copy mode using the -X flag to the send-keys com‐
882 mand. When a key is pressed, copy mode automatically uses one of two key
883 tables, depending on the mode-keys option: copy-mode for emacs, or
884 copy-mode-vi for vi. Key tables may be viewed with the list-keys com‐
885 mand.
886 The following commands are supported in copy mode:
888 append-selection
890 Append the selection to the top paste buffer.
891 append-selection-and-cancel (vi: A)
893 Append the selection to the top paste buffer and exit copy mode.
894 back-to-indentation (vi: ^) (emacs: M-m)
896 Move the cursor back to the indentation.
897 begin-selection (vi: Space) (emacs: C-Space)
899 Begin selection.
900 bottom-line (vi: L)
902 Move to the bottom line.
903 cancel (vi: q) (emacs: Escape)
905 Exit copy mode.
906 clear-selection (vi: Escape) (emacs: C-g)
908 Clear the current selection.
909 copy-end-of-line [prefix]
911 Copy from the cursor position to the end of the line. prefix is
912 used to name the new paste buffer.
913 copy-end-of-line-and-cancel [prefix]
915 Copy from the cursor position and exit copy mode.
916 copy-line [prefix]
918 Copy the entire line.
919 copy-line-and-cancel [prefix]
921 Copy the entire line and exit copy mode.
922 copy-selection [prefix]
924 Copies the current selection.
925 copy-selection-and-cancel [prefix] (vi: Enter) (emacs: M-w)
927 Copy the current selection and exit copy mode.
928 cursor-down (vi: j) (emacs: Down)
930 Move the cursor down.
931 cursor-left (vi: h) (emacs: Left)
933 Move the cursor left.
934 cursor-right (vi: l) (emacs: Right)
936 Move the cursor right.
937 cursor-up (vi: k) (emacs: Up)
939 Move the cursor up.
940 end-of-line (vi: $) (emacs: C-e)
942 Move the cursor to the end of the line.
943 goto-line line (vi: :) (emacs: g)
945 Move the cursor to a specific line.
946 history-bottom (vi: G) (emacs: M->)
948 Scroll to the bottom of the history.
949 history-top (vi: g) (emacs: M-<)
951 Scroll to the top of the history.
952 jump-again (vi: ;) (emacs: ;)
954 Repeat the last jump.
955 jump-backward to (vi: F) (emacs: F)
957 Jump backwards to the specified text.
958 jump-forward to (vi: f) (emacs: f)
960 Jump forward to the specified text.
961 jump-to-mark (vi: M-x) (emacs: M-x)
963 Jump to the last mark.
964 middle-line (vi: M) (emacs: M-r)
966 Move to the middle line.
967 next-matching-bracket (vi: %) (emacs: M-C-f)
969 Move to the next matching bracket.
970 next-paragraph (vi: }) (emacs: M-})
972 Move to the next paragraph.
973 next-prompt [-o]
975 Move to the next prompt.
976 next-word (vi: w)
978 Move to the next word.
979 page-down (vi: C-f) (emacs: PageDown)
981 Scroll down by one page.
982 page-up (vi: C-b) (emacs: PageUp)
984 Scroll up by one page.
985 previous-matching-bracket (emacs: M-C-b)
987 Move to the previous matching bracket.
988 previous-paragraph (vi: {) (emacs: M-{)
990 Move to the previous paragraph.
991 previous-prompt [-o]
993 Move to the previous prompt.
994 previous-word (vi: b) (emacs: M-b)
996 Move to the previous word.
997 rectangle-toggle (vi: v) (emacs: R)
999 Toggle rectangle selection mode.
1000 refresh-from-pane (vi: r) (emacs: r)
1002 Refresh the content from the pane.
1003 search-again (vi: n) (emacs: n)
1005 Repeat the last search.
1006 search-backward text (vi: ?)
1008 Search backwards for the specified text.
1009 search-forward text (vi: /)
1011 Search forward for the specified text.
1012 select-line (vi: V)
1014 Select the current line.
1015 select-word
1017 Select the current word.
1018 start-of-line (vi: 0) (emacs: C-a)
1020 Move the cursor to the start of the line.
1021 top-line (vi: H) (emacs: M-R)
1023 Move to the top line.
1024 The search commands come in several varieties: ‘search-forward’ and
1026 ‘search-backward’ search for a regular expression; the ‘-text’ variants
1027 search for a plain text string rather than a regular expression;
1028 ‘-incremental’ perform an incremental search and expect to be used with
1029 the -i flag to the command-prompt command. ‘search-again’ repeats the
1030 last search and ‘search-reverse’ does the same but reverses the direction
1031 (forward becomes backward and backward becomes forward).
1032 The ‘next-prompt’ and ‘previous-prompt’ move between shell prompts, but
1034 require the shell to emit an escape sequence (\033]133;A\033\\) to tell
1035 tmux where the prompts are located; if the shell does not do this, these
1036 commands will do nothing. The -o flag jumps to the beginning of the com‐
1037 mand output instead of the shell prompt.
1038 Copy commands may take an optional buffer prefix argument which is used
1040 to generate the buffer name (the default is ‘buffer’ so buffers are named
1041 ‘buffer0’, ‘buffer1’ and so on). Pipe commands take a command argument
1042 which is the command to which the selected text is piped. ‘copy-pipe’
1043 variants also copy the selection. The ‘-and-cancel’ variants of some
1044 commands exit copy mode after they have completed (for copy commands) or
1045 when the cursor reaches the bottom (for scrolling commands). ‘-no-clear’
1046 variants do not clear the selection.
1047 The next and previous word keys skip over whitespace and treat consecu‐
1049 tive runs of either word separators or other letters as words. Word sep‐
1050 arators can be customized with the word-separators session option. Next
1051 word moves to the start of the next word, next word end to the end of the
1052 next word and previous word to the start of the previous word. The three
1053 next and previous space keys work similarly but use a space alone as the
1054 word separator. Setting word-separators to the empty string makes
1055 next/previous word equivalent to next/previous space.
1056 The jump commands enable quick movement within a line. For instance,
1058 typing ‘f’ followed by ‘/’ will move the cursor to the next ‘/’ character
1059 on the current line. A ‘;’ will then jump to the next occurrence.
1060 Commands in copy mode may be prefaced by an optional repeat count. With
1062 vi key bindings, a prefix is entered using the number keys; with emacs,
1063 the Alt (meta) key and a number begins prefix entry.
1064 The synopsis for the copy-mode command is:
1066 copy-mode [-eHMqu] [-s src-pane] [-t target-pane]
1068 Enter copy mode. The -u option scrolls one page up. -M begins a
1069 mouse drag (only valid if bound to a mouse key binding, see MOUSE
1070 SUPPORT). -H hides the position indicator in the top right. -q
1071 cancels copy mode and any other modes. -s copies from src-pane
1072 instead of target-pane.
1073 -e specifies that scrolling to the bottom of the history (to the
1075 visible screen) should exit copy mode. While in copy mode,
1076 pressing a key other than those used for scrolling will disable
1077 this behaviour. This is intended to allow fast scrolling through
1078 a pane's history, for example with:
1079 bind PageUp copy-mode -eu
1081 A number of preset arrangements of panes are available, these are called
1083 layouts. These may be selected with the select-layout command or cycled
1084 with next-layout (bound to ‘Space’ by default); once a layout is chosen,
1085 panes within it may be moved and resized as normal.
1086 The following layouts are supported:
1088 even-horizontal
1090 Panes are spread out evenly from left to right across the window.
1091 even-vertical
1093 Panes are spread evenly from top to bottom.
1094 main-horizontal
1096 A large (main) pane is shown at the top of the window and the re‐
1097 maining panes are spread from left to right in the leftover space
1098 at the bottom. Use the main-pane-height window option to specify
1099 the height of the top pane.
1100 main-vertical
1102 Similar to main-horizontal but the large pane is placed on the
1103 left and the others spread from top to bottom along the right.
1104 See the main-pane-width window option.
1105 tiled Panes are spread out as evenly as possible over the window in
1107 both rows and columns.
1108 In addition, select-layout may be used to apply a previously used layout
1110 - the list-windows command displays the layout of each window in a form
1111 suitable for use with select-layout. For example:
1112 $ tmux list-windows
1114 0: ksh [159x48]
1115 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1116 $ tmux select-layout 'bb62,159x48,0,0{79x48,0,0,79x48,80,0}'
1117 tmux automatically adjusts the size of the layout for the current window
1119 size. Note that a layout cannot be applied to a window with more panes
1120 than that from which the layout was originally defined.
1121 Commands related to windows and panes are as follows:
1123 break-pane [-abdP] [-F format] [-n window-name] [-s src-pane] [-t
1125 dst-window]
1126 (alias: breakp)
1127 Break src-pane off from its containing window to make it the only
1128 pane in dst-window. With -a or -b, the window is moved to the
1129 next index after or before (existing windows are moved if neces‐
1130 sary). If -d is given, the new window does not become the cur‐
1131 rent window. The -P option prints information about the new win‐
1132 dow after it has been created. By default, it uses the format
1133 ‘#{session_name}:#{window_index}.#{pane_index}’ but a different
1134 format may be specified with -F.
1135 capture-pane [-aAepPqCJN] [-b buffer-name] [-E end-line] [-S start-line]
1137 [-t target-pane]
1138 (alias: capturep)
1139 Capture the contents of a pane. If -p is given, the output goes
1140 to stdout, otherwise to the buffer specified with -b or a new
1141 buffer if omitted. If -a is given, the alternate screen is used,
1142 and the history is not accessible. If no alternate screen ex‐
1143 ists, an error will be returned unless -q is given. If -e is
1144 given, the output includes escape sequences for text and back‐
1145 ground attributes. -C also escapes non-printable characters as
1146 octal \xxx. -T ignores trailing positions that do not contain a
1147 character. -N preserves trailing spaces at each line's end and
1148 -J preserves trailing spaces and joins any wrapped lines; -J im‐
1149 plies -T. -P captures only any output that the pane has received
1150 that is the beginning of an as-yet incomplete escape sequence.
1151 -S and -E specify the starting and ending line numbers, zero is
1153 the first line of the visible pane and negative numbers are lines
1154 in the history. ‘-’ to -S is the start of the history and to -E
1155 the end of the visible pane. The default is to capture only the
1156 visible contents of the pane.
1157 choose-client [-NrZ] [-F format] [-f filter] [-K key-format] [-O
1159 sort-order] [-t target-pane] [template]
1160 Put a pane into client mode, allowing a client to be selected in‐
1161 teractively from a list. Each client is shown on one line. A
1162 shortcut key is shown on the left in brackets allowing for imme‐
1163 diate choice, or the list may be navigated and an item chosen or
1164 otherwise manipulated using the keys below. -Z zooms the pane.
1165 The following keys may be used in client mode:
1166 Key Function
1168 Enter Choose selected client
1169 Up Select previous client
1170 Down Select next client
1171 C-s Search by name
1172 n Repeat last search
1173 t Toggle if client is tagged
1174 T Tag no clients
1175 C-t Tag all clients
1176 d Detach selected client
1177 D Detach tagged clients
1178 x Detach and HUP selected client
1179 X Detach and HUP tagged clients
1180 z Suspend selected client
1181 Z Suspend tagged clients
1182 f Enter a format to filter items
1183 O Change sort field
1184 r Reverse sort order
1185 v Toggle preview
1186 q Exit mode
1187 After a client is chosen, ‘%%’ is replaced by the client name in
1189 template and the result executed as a command. If template is
1190 not given, "detach-client -t '%%'" is used.
1191 -O specifies the initial sort field: one of ‘name’, ‘size’,
1193 ‘creation’ (time), or ‘activity’ (time). -r reverses the sort
1194 order. -f specifies an initial filter: the filter is a format -
1195 if it evaluates to zero, the item in the list is not shown, oth‐
1196 erwise it is shown. If a filter would lead to an empty list, it
1197 is ignored. -F specifies the format for each item in the list
1198 and -K a format for each shortcut key; both are evaluated once
1199 for each line. -N starts without the preview. This command
1200 works only if at least one client is attached.
1201 choose-tree [-GNrswZ] [-F format] [-f filter] [-K key-format] [-O
1203 sort-order] [-t target-pane] [template]
1204 Put a pane into tree mode, where a session, window or pane may be
1205 chosen interactively from a tree. Each session, window or pane
1206 is shown on one line. A shortcut key is shown on the left in
1207 brackets allowing for immediate choice, or the tree may be navi‐
1208 gated and an item chosen or otherwise manipulated using the keys
1209 below. -s starts with sessions collapsed and -w with windows
1210 collapsed. -Z zooms the pane. The following keys may be used in
1211 tree mode:
1212 Key Function
1214 Enter Choose selected item
1215 Up Select previous item
1216 Down Select next item
1217 + Expand selected item
1218 - Collapse selected item
1219 M-+ Expand all items
1220 M-- Collapse all items
1221 x Kill selected item
1222 X Kill tagged items
1223 < Scroll list of previews left
1224 > Scroll list of previews right
1225 C-s Search by name
1226 m Set the marked pane
1227 M Clear the marked pane
1228 n Repeat last search
1229 t Toggle if item is tagged
1230 T Tag no items
1231 C-t Tag all items
1232 : Run a command for each tagged item
1233 f Enter a format to filter items
1234 H Jump to the starting pane
1235 O Change sort field
1236 r Reverse sort order
1237 v Toggle preview
1238 q Exit mode
1239 After a session, window or pane is chosen, the first instance of
1241 ‘%%’ and all instances of ‘%1’ are replaced by the target in
1242 template and the result executed as a command. If template is
1243 not given, "switch-client -t '%%'" is used.
1244 -O specifies the initial sort field: one of ‘index’, ‘name’, or
1246 ‘time’ (activity). -r reverses the sort order. -f specifies an
1247 initial filter: the filter is a format - if it evaluates to zero,
1248 the item in the list is not shown, otherwise it is shown. If a
1249 filter would lead to an empty list, it is ignored. -F specifies
1250 the format for each item in the tree and -K a format for each
1251 shortcut key; both are evaluated once for each line. -N starts
1252 without the preview. -G includes all sessions in any session
1253 groups in the tree rather than only the first. This command
1254 works only if at least one client is attached.
1255 customize-mode [-NZ] [-F format] [-f filter] [-t target-pane] [template]
1257 Put a pane into customize mode, where options and key bindings
1258 may be browsed and modified from a list. Option values in the
1259 list are shown for the active pane in the current window. -Z
1260 zooms the pane. The following keys may be used in customize
1261 mode:
1262 Key Function
1264 Enter Set pane, window, session or global option value
1265 Up Select previous item
1266 Down Select next item
1267 + Expand selected item
1268 - Collapse selected item
1269 M-+ Expand all items
1270 M-- Collapse all items
1271 s Set option value or key attribute
1272 S Set global option value
1273 w Set window option value, if option is for pane and
1274 window
1275 d Set an option or key to the default
1276 D Set tagged options and tagged keys to the default
1277 u Unset an option (set to default value if global) or
1278 unbind a key
1279 U Unset tagged options and unbind tagged keys
1280 C-s Search by name
1281 n Repeat last search
1282 t Toggle if item is tagged
1283 T Tag no items
1284 C-t Tag all items
1285 f Enter a format to filter items
1286 v Toggle option information
1287 q Exit mode
1288 -f specifies an initial filter: the filter is a format - if it
1290 evaluates to zero, the item in the list is not shown, otherwise
1291 it is shown. If a filter would lead to an empty list, it is ig‐
1292 nored. -F specifies the format for each item in the tree. -N
1293 starts without the option information. This command works only
1294 if at least one client is attached.
1295 display-panes [-bN] [-d duration] [-t target-client] [template]
1297 (alias: displayp)
1298 Display a visible indicator of each pane shown by target-client.
1299 See the display-panes-colour and display-panes-active-colour ses‐
1300 sion options. The indicator is closed when a key is pressed (un‐
1301 less -N is given) or duration milliseconds have passed. If -d is
1302 not given, display-panes-time is used. A duration of zero means
1303 the indicator stays until a key is pressed. While the indicator
1304 is on screen, a pane may be chosen with the ‘0’ to ‘9’ keys,
1305 which will cause template to be executed as a command with ‘%%’
1306 substituted by the pane ID. The default template is "select-pane
1307 -t '%%'". With -b, other commands are not blocked from running
1308 until the indicator is closed.
1309 find-window [-iCNrTZ] [-t target-pane] match-string
1311 (alias: findw)
1312 Search for a fnmatch(3) pattern or, with -r, regular expression
1313 match-string in window names, titles, and visible content (but
1314 not history). The flags control matching behavior: -C matches
1315 only visible window contents, -N matches only the window name and
1316 -T matches only the window title. -i makes the search ignore
1317 case. The default is -CNT. -Z zooms the pane.
1318 This command works only if at least one client is attached.
1320 join-pane [-bdfhv] [-l size] [-s src-pane] [-t dst-pane]
1322 (alias: joinp)
1323 Like split-window, but instead of splitting dst-pane and creating
1324 a new pane, split it and move src-pane into the space. This can
1325 be used to reverse break-pane. The -b option causes src-pane to
1326 be joined to left of or above dst-pane.
1327 If -s is omitted and a marked pane is present (see select-pane
1329 -m), the marked pane is used rather than the current pane.
1330 kill-pane [-a] [-t target-pane]
1332 (alias: killp)
1333 Destroy the given pane. If no panes remain in the containing
1334 window, it is also destroyed. The -a option kills all but the
1335 pane given with -t.
1336 kill-window [-a] [-t target-window]
1338 (alias: killw)
1339 Kill the current window or the window at target-window, removing
1340 it from any sessions to which it is linked. The -a option kills
1341 all but the window given with -t.
1342 last-pane [-deZ] [-t target-window]
1344 (alias: lastp)
1345 Select the last (previously selected) pane. -Z keeps the window
1346 zoomed if it was zoomed. -e enables or -d disables input to the
1347 pane.
1348 last-window [-t target-session]
1350 (alias: last)
1351 Select the last (previously selected) window. If no
1352 target-session is specified, select the last window of the cur‐
1353 rent session.
1354 link-window [-abdk] [-s src-window] [-t dst-window]
1356 (alias: linkw)
1357 Link the window at src-window to the specified dst-window. If
1358 dst-window is specified and no such window exists, the src-window
1359 is linked there. With -a or -b the window is moved to the next
1360 index after or before dst-window (existing windows are moved if
1361 necessary). If -k is given and dst-window exists, it is killed,
1362 otherwise an error is generated. If -d is given, the newly
1363 linked window is not selected.
1364 list-panes [-as] [-F format] [-f filter] [-t target]
1366 (alias: lsp)
1367 If -a is given, target is ignored and all panes on the server are
1368 listed. If -s is given, target is a session (or the current ses‐
1369 sion). If neither is given, target is a window (or the current
1370 window). -F specifies the format of each line and -f a filter.
1371 Only panes for which the filter is true are shown. See the
1372 FORMATS section.
1373 list-windows [-a] [-F format] [-f filter] [-t target-session]
1375 (alias: lsw)
1376 If -a is given, list all windows on the server. Otherwise, list
1377 windows in the current session or in target-session. -F speci‐
1378 fies the format of each line and -f a filter. Only windows for
1379 which the filter is true are shown. See the FORMATS section.
1380 move-pane [-bdfhv] [-l size] [-s src-pane] [-t dst-pane]
1382 (alias: movep)
1383 Does the same as join-pane.
1384 move-window [-abrdk] [-s src-window] [-t dst-window]
1386 (alias: movew)
1387 This is similar to link-window, except the window at src-window
1388 is moved to dst-window. With -r, all windows in the session are
1389 renumbered in sequential order, respecting the base-index option.
1390 new-window [-abdkPS] [-c start-directory] [-e environment] [-F format]
1392 [-n window-name] [-t target-window] [shell-command]
1393 (alias: neww)
1394 Create a new window. With -a or -b, the new window is inserted
1395 at the next index after or before the specified target-window,
1396 moving windows up if necessary; otherwise target-window is the
1397 new window location.
1398 If -d is given, the session does not make the new window the cur‐
1400 rent window. target-window represents the window to be created;
1401 if the target already exists an error is shown, unless the -k
1402 flag is used, in which case it is destroyed. If -S is given and
1403 a window named window-name already exists, it is selected (unless
1404 -d is also given in which case the command does nothing).
1405 shell-command is the command to execute. If shell-command is not
1407 specified, the value of the default-command option is used. -c
1408 specifies the working directory in which the new window is cre‐
1409 ated.
1410 When the shell command completes, the window closes. See the
1412 remain-on-exit option to change this behaviour.
1413 -e takes the form ‘VARIABLE=value’ and sets an environment vari‐
1415 able for the newly created window; it may be specified multiple
1416 times.
1417 The TERM environment variable must be set to ‘screen’ or ‘tmux’
1419 for all programs running inside tmux. New windows will automati‐
1420 cally have ‘TERM=screen’ added to their environment, but care
1421 must be taken not to reset this in shell start-up files or by the
1422 -e option.
1423 The -P option prints information about the new window after it
1425 has been created. By default, it uses the format
1426 ‘#{session_name}:#{window_index}’ but a different format may be
1427 specified with -F.
1428 next-layout [-t target-window]
1430 (alias: nextl)
1431 Move a window to the next layout and rearrange the panes to fit.
1432 next-window [-a] [-t target-session]
1434 (alias: next)
1435 Move to the next window in the session. If -a is used, move to
1436 the next window with an alert.
1437 pipe-pane [-IOo] [-t target-pane] [shell-command]
1439 (alias: pipep)
1440 Pipe output sent by the program in target-pane to a shell command
1441 or vice versa. A pane may only be connected to one command at a
1442 time, any existing pipe is closed before shell-command is exe‐
1443 cuted. The shell-command string may contain the special charac‐
1444 ter sequences supported by the status-left option. If no
1445 shell-command is given, the current pipe (if any) is closed.
1446 -I and -O specify which of the shell-command output streams are
1448 connected to the pane: with -I stdout is connected (so anything
1449 shell-command prints is written to the pane as if it were typed);
1450 with -O stdin is connected (so any output in the pane is piped to
1451 shell-command). Both may be used together and if neither are
1452 specified, -O is used.
1453 The -o option only opens a new pipe if no previous pipe exists,
1455 allowing a pipe to be toggled with a single key, for example:
1456 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
1458 previous-layout [-t target-window]
1460 (alias: prevl)
1461 Move to the previous layout in the session.
1462 previous-window [-a] [-t target-session]
1464 (alias: prev)
1465 Move to the previous window in the session. With -a, move to the
1466 previous window with an alert.
1467 rename-window [-t target-window] new-name
1469 (alias: renamew)
1470 Rename the current window, or the window at target-window if
1471 specified, to new-name.
1472 resize-pane [-DLMRTUZ] [-t target-pane] [-x width] [-y height]
1474 [adjustment]
1475 (alias: resizep)
1476 Resize a pane, up, down, left or right by adjustment with -U, -D,
1477 -L or -R, or to an absolute size with -x or -y. The adjustment
1478 is given in lines or columns (the default is 1); -x and -y may be
1479 a given as a number of lines or columns or followed by ‘%’ for a
1480 percentage of the window size (for example ‘-x 10%’). With -Z,
1481 the active pane is toggled between zoomed (occupying the whole of
1482 the window) and unzoomed (its normal position in the layout).
1483 -M begins mouse resizing (only valid if bound to a mouse key
1485 binding, see MOUSE SUPPORT).
1486 -T trims all lines below the current cursor position and moves
1488 lines out of the history to replace them.
1489 resize-window [-aADLRU] [-t target-window] [-x width] [-y height]
1491 [adjustment]
1492 (alias: resizew)
1493 Resize a window, up, down, left or right by adjustment with -U,
1494 -D, -L or -R, or to an absolute size with -x or -y. The
1495 adjustment is given in lines or cells (the default is 1). -A
1496 sets the size of the largest session containing the window; -a
1497 the size of the smallest. This command will automatically set
1498 window-size to manual in the window options.
1499 respawn-pane [-k] [-c start-directory] [-e environment] [-t target-pane]
1501 [shell-command]
1502 (alias: respawnp)
1503 Reactivate a pane in which the command has exited (see the
1504 remain-on-exit window option). If shell-command is not given,
1505 the command used when the pane was created or last respawned is
1506 executed. The pane must be already inactive, unless -k is given,
1507 in which case any existing command is killed. -c specifies a new
1508 working directory for the pane. The -e option has the same mean‐
1509 ing as for the new-window command.
1510 respawn-window [-k] [-c start-directory] [-e environment] [-t
1512 target-window] [shell-command]
1513 (alias: respawnw)
1514 Reactivate a window in which the command has exited (see the
1515 remain-on-exit window option). If shell-command is not given,
1516 the command used when the window was created or last respawned is
1517 executed. The window must be already inactive, unless -k is
1518 given, in which case any existing command is killed. -c speci‐
1519 fies a new working directory for the window. The -e option has
1520 the same meaning as for the new-window command.
1521 rotate-window [-DUZ] [-t target-window]
1523 (alias: rotatew)
1524 Rotate the positions of the panes within a window, either upward
1525 (numerically lower) with -U or downward (numerically higher). -Z
1526 keeps the window zoomed if it was zoomed.
1527 select-layout [-Enop] [-t target-pane] [layout-name]
1529 (alias: selectl)
1530 Choose a specific layout for a window. If layout-name is not
1531 given, the last preset layout used (if any) is reapplied. -n and
1532 -p are equivalent to the next-layout and previous-layout com‐
1533 mands. -o applies the last set layout if possible (undoes the
1534 most recent layout change). -E spreads the current pane and any
1535 panes next to it out evenly.
1536 select-pane [-DdeLlMmRUZ] [-T title] [-t target-pane]
1538 (alias: selectp)
1539 Make pane target-pane the active pane in its window. If one of
1540 -D, -L, -R, or -U is used, respectively the pane below, to the
1541 left, to the right, or above the target pane is used. -Z keeps
1542 the window zoomed if it was zoomed. -l is the same as using the
1543 last-pane command. -e enables or -d disables input to the pane.
1544 -T sets the pane title.
1545 -m and -M are used to set and clear the marked pane. There is
1547 one marked pane at a time, setting a new marked pane clears the
1548 last. The marked pane is the default target for -s to join-pane,
1549 move-pane, swap-pane and swap-window.
1550 select-window [-lnpT] [-t target-window]
1552 (alias: selectw)
1553 Select the window at target-window. -l, -n and -p are equivalent
1554 to the last-window, next-window and previous-window commands. If
1555 -T is given and the selected window is already the current win‐
1556 dow, the command behaves like last-window.
1557 split-window [-bdfhIvPZ] [-c start-directory] [-e environment] [-l size]
1559 [-t target-pane] [shell-command] [-F format]
1560 (alias: splitw)
1561 Create a new pane by splitting target-pane: -h does a horizontal
1562 split and -v a vertical split; if neither is specified, -v is as‐
1563 sumed. The -l option specifies the size of the new pane in lines
1564 (for vertical split) or in columns (for horizontal split); size
1565 may be followed by ‘%’ to specify a percentage of the available
1566 space. The -b option causes the new pane to be created to the
1567 left of or above target-pane. The -f option creates a new pane
1568 spanning the full window height (with -h) or full window width
1569 (with -v), instead of splitting the active pane. -Z zooms if the
1570 window is not zoomed, or keeps it zoomed if already zoomed.
1571 An empty shell-command ('') will create a pane with no command
1573 running in it. Output can be sent to such a pane with the
1574 display-message command. The -I flag (if shell-command is not
1575 specified or empty) will create an empty pane and forward any
1576 output from stdin to it. For example:
1577 $ make 2>&1|tmux splitw -dI &
1579 All other options have the same meaning as for the new-window
1581 command.
1582 swap-pane [-dDUZ] [-s src-pane] [-t dst-pane]
1584 (alias: swapp)
1585 Swap two panes. If -U is used and no source pane is specified
1586 with -s, dst-pane is swapped with the previous pane (before it
1587 numerically); -D swaps with the next pane (after it numerically).
1588 -d instructs tmux not to change the active pane and -Z keeps the
1589 window zoomed if it was zoomed.
1590 If -s is omitted and a marked pane is present (see select-pane
1592 -m), the marked pane is used rather than the current pane.
1593 swap-window [-d] [-s src-window] [-t dst-window]
1595 (alias: swapw)
1596 This is similar to link-window, except the source and destination
1597 windows are swapped. It is an error if no window exists at
1598 src-window. If -d is given, the new window does not become the
1599 current window.
1600 If -s is omitted and a marked pane is present (see select-pane
1602 -m), the window containing the marked pane is used rather than
1603 the current window.
1604 unlink-window [-k] [-t target-window]
1606 (alias: unlinkw)
1607 Unlink target-window. Unless -k is given, a window may be un‐
1608 linked only if it is linked to multiple sessions - windows may
1609 not be linked to no sessions; if -k is specified and the window
1610 is linked to only one session, it is unlinked and destroyed.
1611
1613 tmux allows a command to be bound to most keys, with or without a prefix
1614 key. When specifying keys, most represent themselves (for example ‘A’ to
1615 ‘Z’). Ctrl keys may be prefixed with ‘C-’ or ‘^’, Shift keys with ‘S-’
1616 and Alt (meta) with ‘M-’. In addition, the following special key names
1617 are accepted: Up, Down, Left, Right, BSpace, BTab, DC (Delete), End,
1618 Enter, Escape, F1 to F12, Home, IC (Insert), NPage/PageDown/PgDn,
1619 PPage/PageUp/PgUp, Space, and Tab. Note that to bind the ‘"’ or ‘'’
1620 keys, quotation marks are necessary, for example:
1621 bind-key '"' split-window
1623 bind-key "'" new-window
1624 A command bound to the Any key will execute for all keys which do not
1626 have a more specific binding.
1627 Commands related to key bindings are as follows:
1629 bind-key [-nr] [-N note] [-T key-table] key command [argument ...]
1631 (alias: bind)
1632 Bind key key to command. Keys are bound in a key table. By de‐
1633 fault (without -T), the key is bound in the prefix key table.
1634 This table is used for keys pressed after the prefix key (for ex‐
1635 ample, by default ‘c’ is bound to new-window in the prefix table,
1636 so ‘C-b c’ creates a new window). The root table is used for
1637 keys pressed without the prefix key: binding ‘c’ to new-window in
1638 the root table (not recommended) means a plain ‘c’ will create a
1639 new window. -n is an alias for -T root. Keys may also be bound
1640 in custom key tables and the switch-client -T command used to
1641 switch to them from a key binding. The -r flag indicates this
1642 key may repeat, see the repeat-time option. -N attaches a note
1643 to the key (shown with list-keys -N).
1644 To view the default bindings and possible commands, see the
1646 list-keys command.
1647 list-keys [-1aN] [-P prefix-string -T key-table] [key]
1649 (alias: lsk)
1650 List key bindings. There are two forms: the default lists keys
1651 as bind-key commands; -N lists only keys with attached notes and
1652 shows only the key and note for each key.
1653 With the default form, all key tables are listed by default. -T
1655 lists only keys in key-table.
1656 With the -N form, only keys in the root and prefix key tables are
1658 listed by default; -T also lists only keys in key-table. -P
1659 specifies a prefix to print before each key and -1 lists only the
1660 first matching key. -a lists the command for keys that do not
1661 have a note rather than skipping them.
1662 send-keys [-FHKlMRX] [-c target-client] [-N repeat-count] [-t
1664 target-pane] key ...
1665 (alias: send)
1666 Send a key or keys to a window or client. Each argument key is
1667 the name of the key (such as ‘C-a’ or ‘NPage’) to send; if the
1668 string is not recognised as a key, it is sent as a series of
1669 characters. If -K is given, keys are sent to target-client, so
1670 they are looked up in the client's key table, rather than to
1671 target-pane. All arguments are sent sequentially from first to
1672 last. If no keys are given and the command is bound to a key,
1673 then that key is used.
1674 The -l flag disables key name lookup and processes the keys as
1676 literal UTF-8 characters. The -H flag expects each key to be a
1677 hexadecimal number for an ASCII character.
1678 The -R flag causes the terminal state to be reset.
1680 -M passes through a mouse event (only valid if bound to a mouse
1682 key binding, see MOUSE SUPPORT).
1683 -X is used to send a command into copy mode - see the WINDOWS AND
1685 PANES section. -N specifies a repeat count and -F expands for‐
1686 mats in arguments where appropriate.
1687 send-prefix [-2] [-t target-pane]
1689 Send the prefix key, or with -2 the secondary prefix key, to a
1690 window as if it was pressed.
1691 unbind-key [-anq] [-T key-table] key
1693 (alias: unbind)
1694 Unbind the command bound to key. -n and -T are the same as for
1695 bind-key. If -a is present, all key bindings are removed. The
1696 -q option prevents errors being returned.
1697
1699 The appearance and behaviour of tmux may be modified by changing the
1700 value of various options. There are four types of option: server
1701 options, session options, window options, and pane options.
1702 The tmux server has a set of global server options which do not apply to
1704 any particular window or session or pane. These are altered with the
1705 set-option -s command, or displayed with the show-options -s command.
1706 In addition, each individual session may have a set of session options,
1708 and there is a separate set of global session options. Sessions which do
1709 not have a particular option configured inherit the value from the global
1710 session options. Session options are set or unset with the set-option
1711 command and may be listed with the show-options command. The available
1712 server and session options are listed under the set-option command.
1713 Similarly, a set of window options is attached to each window and a set
1715 of pane options to each pane. Pane options inherit from window options.
1716 This means any pane option may be set as a window option to apply the op‐
1717 tion to all panes in the window without the option set, for example these
1718 commands will set the background colour to red for all panes except pane
1719 0:
1720 set -w window-style bg=red
1722 set -pt:.0 window-style bg=blue
1723 There is also a set of global window options from which any unset window
1725 or pane options are inherited. Window and pane options are altered with
1726 set-option -w and -p commands and displayed with show-option -w and -p.
1727 tmux also supports user options which are prefixed with a ‘@’. User op‐
1729 tions may have any name, so long as they are prefixed with ‘@’, and be
1730 set to any string. For example:
1731 $ tmux set -wq @foo "abc123"
1733 $ tmux show -wv @foo
1734 abc123
1735 Commands which set options are as follows:
1737 set-option [-aFgopqsuUw] [-t target-pane] option value
1739 (alias: set)
1740 Set a pane option with -p, a window option with -w, a server op‐
1741 tion with -s, otherwise a session option. If the option is not a
1742 user option, -w or -s may be unnecessary - tmux will infer the
1743 type from the option name, assuming -w for pane options. If -g
1744 is given, the global session or window option is set.
1745 -F expands formats in the option value. The -u flag unsets an
1747 option, so a session inherits the option from the global options
1748 (or with -g, restores a global option to the default). -U unsets
1749 an option (like -u) but if the option is a pane option also un‐
1750 sets the option on any panes in the window. value depends on the
1751 option and may be a number, a string, or a flag (on, off, or
1752 omitted to toggle).
1753 The -o flag prevents setting an option that is already set and
1755 the -q flag suppresses errors about unknown or ambiguous options.
1756 With -a, and if the option expects a string or a style, value is
1758 appended to the existing setting. For example:
1759 set -g status-left "foo"
1761 set -ag status-left "bar"
1762 Will result in ‘foobar’. And:
1764 set -g status-style "bg=red"
1766 set -ag status-style "fg=blue"
1767 Will result in a red background and blue foreground. Without -a,
1769 the result would be the default background and a blue foreground.
1770 show-options [-AgHpqsvw] [-t target-pane] [option]
1772 (alias: show)
1773 Show the pane options (or a single option if option is provided)
1774 with -p, the window options with -w, the server options with -s,
1775 otherwise the session options. If the option is not a user op‐
1776 tion, -w or -s may be unnecessary - tmux will infer the type from
1777 the option name, assuming -w for pane options. Global session or
1778 window options are listed if -g is used. -v shows only the op‐
1779 tion value, not the name. If -q is set, no error will be re‐
1780 turned if option is unset. -H includes hooks (omitted by de‐
1781 fault). -A includes options inherited from a parent set of op‐
1782 tions, such options are marked with an asterisk.
1783 Available server options are:
1785 backspace key
1787 Set the key sent by tmux for backspace.
1788 buffer-limit number
1790 Set the number of buffers; as new buffers are added to the top of
1791 the stack, old ones are removed from the bottom if necessary to
1792 maintain this maximum length.
1793 command-alias[] name=value
1795 This is an array of custom aliases for commands. If an unknown
1796 command matches name, it is replaced with value. For example,
1797 after:
1798 set -s command-alias[100] zoom='resize-pane -Z'
1800 Using:
1802 zoom -t:.1
1804 Is equivalent to:
1806 resize-pane -Z -t:.1
1808 Note that aliases are expanded when a command is parsed rather
1810 than when it is executed, so binding an alias with bind-key will
1811 bind the expanded form.
1812 default-terminal terminal
1814 Set the default terminal for new windows created in this session
1815 - the default value of the TERM environment variable. For tmux
1816 to work correctly, this must be set to ‘screen’, ‘tmux’ or a de‐
1817 rivative of them.
1818 copy-command shell-command
1820 Give the command to pipe to if the copy-pipe copy mode command is
1821 used without arguments.
1822 escape-time time
1824 Set the time in milliseconds for which tmux waits after an escape
1825 is input to determine if it is part of a function or meta key se‐
1826 quences. The default is 500 milliseconds.
1827 editor shell-command
1829 Set the command used when tmux runs an editor.
1830 exit-empty [on | off]
1832 If enabled (the default), the server will exit when there are no
1833 active sessions.
1834 exit-unattached [on | off]
1836 If enabled, the server will exit when there are no attached
1837 clients.
1838 extended-keys [on | off | always]
1840 When on or always, the escape sequence to enable extended keys is
1841 sent to the terminal, if tmux knows that it is supported. tmux
1842 always recognises extended keys itself. If this option is on,
1843 tmux will only forward extended keys to applications when they
1844 request them; if always, tmux will always forward the keys.
1845 focus-events [on | off]
1847 When enabled, focus events are requested from the terminal if
1848 supported and passed through to applications running in tmux.
1849 Attached clients should be detached and attached again after
1850 changing this option.
1851 history-file path
1853 If not empty, a file to which tmux will write command prompt his‐
1854 tory on exit and load it from on start.
1855 message-limit number
1857 Set the number of error or information messages to save in the
1858 message log for each client.
1859 prompt-history-limit number
1861 Set the number of history items to save in the history file for
1862 each type of command prompt.
1863 set-clipboard [on | external | off]
1865 Attempt to set the terminal clipboard content using the xterm(1)
1866 escape sequence, if there is an Ms entry in the terminfo(5) de‐
1867 scription (see the TERMINFO EXTENSIONS section).
1868 If set to on, tmux will both accept the escape sequence to create
1870 a buffer and attempt to set the terminal clipboard. If set to
1871 external, tmux will attempt to set the terminal clipboard but ig‐
1872 nore attempts by applications to set tmux buffers. If off, tmux
1873 will neither accept the clipboard escape sequence nor attempt to
1874 set the clipboard.
1875 Note that this feature needs to be enabled in xterm(1) by setting
1877 the resource:
1878 disallowedWindowOps: 20,21,SetXprop
1880 Or changing this property from the xterm(1) interactive menu when
1882 required.
1883 terminal-features[] string
1885 Set terminal features for terminal types read from terminfo(5).
1886 tmux has a set of named terminal features. Each will apply ap‐
1887 propriate changes to the terminfo(5) entry in use.
1888 tmux can detect features for a few common terminals; this option
1890 can be used to easily tell tmux about features supported by ter‐
1891 minals it cannot detect. The terminal-overrides option allows
1892 individual terminfo(5) capabilities to be set instead,
1893 terminal-features is intended for classes of functionality sup‐
1894 ported in a standard way but not reported by terminfo(5). Care
1895 must be taken to configure this only with features the terminal
1896 actually supports.
1897 This is an array option where each entry is a colon-separated
1899 string made up of a terminal type pattern (matched using
1900 fnmatch(3)) followed by a list of terminal features. The avail‐
1901 able features are:
1902 256 Supports 256 colours with the SGR escape sequences.
1904 clipboard
1906 Allows setting the system clipboard.
1907 ccolour
1909 Allows setting the cursor colour.
1910 cstyle Allows setting the cursor style.
1912 extkeys
1914 Supports extended keys.
1915 focus Supports focus reporting.
1917 hyperlinks
1919 Supports OSC 8 hyperlinks.
1920 ignorefkeys
1922 Ignore function keys from terminfo(5) and use the tmux
1923 internal set only.
1924 margins
1926 Supports DECSLRM margins.
1927 mouse Supports xterm(1) mouse sequences.
1929 osc7 Supports the OSC 7 working directory extension.
1931 overline
1933 Supports the overline SGR attribute.
1934 rectfill
1936 Supports the DECFRA rectangle fill escape sequence.
1937 RGB Supports RGB colour with the SGR escape sequences.
1939 sixel Supports SIXEL graphics.
1941 strikethrough
1943 Supports the strikethrough SGR escape sequence.
1944 sync Supports synchronized updates.
1946 title Supports xterm(1) title setting.
1948 usstyle
1950 Allows underscore style and colour to be set.
1951 terminal-overrides[] string
1953 Allow terminal descriptions read using terminfo(5) to be overrid‐
1954 den. Each entry is a colon-separated string made up of a termi‐
1955 nal type pattern (matched using fnmatch(3)) and a set of
1956 name=value entries.
1957 For example, to set the ‘clear’ terminfo(5) entry to ‘\e[H\e[2J’
1959 for all terminal types matching ‘rxvt*’:
1960 rxvt*:clear=\e[H\e[2J
1962 The terminal entry value is passed through strunvis(3) before in‐
1964 terpretation.
1965 user-keys[] key
1967 Set list of user-defined key escape sequences. Each item is as‐
1968 sociated with a key named ‘User0’, ‘User1’, and so on.
1969 For example:
1971 set -s user-keys[0] "\e[5;30012~"
1973 bind User0 resize-pane -L 3
1974 Available session options are:
1976 activity-action [any | none | current | other]
1978 Set action on window activity when monitor-activity is on. any
1979 means activity in any window linked to a session causes a bell or
1980 message (depending on visual-activity) in the current window of
1981 that session, none means all activity is ignored (equivalent to
1982 monitor-activity being off), current means only activity in win‐
1983 dows other than the current window are ignored and other means
1984 activity in the current window is ignored but not those in other
1985 windows.
1986 assume-paste-time milliseconds
1988 If keys are entered faster than one in milliseconds, they are as‐
1989 sumed to have been pasted rather than typed and tmux key bindings
1990 are not processed. The default is one millisecond and zero dis‐
1991 ables.
1992 base-index index
1994 Set the base index from which an unused index should be searched
1995 when a new window is created. The default is zero.
1996 bell-action [any | none | current | other]
1998 Set action on a bell in a window when monitor-bell is on. The
1999 values are the same as those for activity-action.
2000 default-command shell-command
2002 Set the command used for new windows (if not specified when the
2003 window is created) to shell-command, which may be any sh(1) com‐
2004 mand. The default is an empty string, which instructs tmux to
2005 create a login shell using the value of the default-shell option.
2006 default-shell path
2008 Specify the default shell. This is used as the login shell for
2009 new windows when the default-command option is set to empty, and
2010 must be the full path of the executable. When started tmux tries
2011 to set a default value from the first suitable of the SHELL envi‐
2012 ronment variable, the shell returned by getpwuid(3), or /bin/sh.
2013 This option should be configured when tmux is used as a login
2014 shell.
2015 default-size XxY
2017 Set the default size of new windows when the window-size option
2018 is set to manual or when a session is created with new-session
2019 -d. The value is the width and height separated by an ‘x’ char‐
2020 acter. The default is 80x24.
2021 destroy-unattached [on | off]
2023 If enabled and the session is no longer attached to any clients,
2024 it is destroyed.
2025 detach-on-destroy [off | on | no-detached | previous | next]
2027 If on (the default), the client is detached when the session it
2028 is attached to is destroyed. If off, the client is switched to
2029 the most recently active of the remaining sessions. If
2030 no-detached, the client is detached only if there are no detached
2031 sessions; if detached sessions exist, the client is switched to
2032 the most recently active. If previous or next, the client is
2033 switched to the previous or next session in alphabetical order.
2034 display-panes-active-colour colour
2036 Set the colour used by the display-panes command to show the in‐
2037 dicator for the active pane.
2038 display-panes-colour colour
2040 Set the colour used by the display-panes command to show the in‐
2041 dicators for inactive panes.
2042 display-panes-time time
2044 Set the time in milliseconds for which the indicators shown by
2045 the display-panes command appear.
2046 display-time time
2048 Set the amount of time for which status line messages and other
2049 on-screen indicators are displayed. If set to 0, messages and
2050 indicators are displayed until a key is pressed. time is in mil‐
2051 liseconds.
2052 history-limit lines
2054 Set the maximum number of lines held in window history. This
2055 setting applies only to new windows - existing window histories
2056 are not resized and retain the limit at the point they were cre‐
2057 ated.
2058 key-table key-table
2060 Set the default key table to key-table instead of root.
2061 lock-after-time number
2063 Lock the session (like the lock-session command) after number
2064 seconds of inactivity. The default is not to lock (set to 0).
2065 lock-command shell-command
2067 Command to run when locking each client. The default is to run
2068 lock(1) with -np.
2069 menu-style style
2071 Set the menu style. See the STYLES section on how to specify
2072 style. Attributes are ignored.
2073 menu-selected-style style
2075 Set the selected menu item style. See the STYLES section on how
2076 to specify style. Attributes are ignored.
2077 menu-border-style style
2079 Set the menu border style. See the STYLES section on how to
2080 specify style. Attributes are ignored.
2081 menu-border-lines type
2083 Set the type of characters used for drawing menu borders. See
2084 popup-border-lines for possible values for border-lines.
2085 message-command-style style
2087 Set status line message command style. This is used for the com‐
2088 mand prompt with vi(1) keys when in command mode. For how to
2089 specify style, see the STYLES section.
2090 message-line [0 | 1 | 2 | 3 | 4]
2092 Set line on which status line messages and the command prompt are
2093 shown.
2094 message-style style
2096 Set status line message style. This is used for messages and for
2097 the command prompt. For how to specify style, see the STYLES
2098 section.
2099 mouse [on | off]
2101 If on, tmux captures the mouse and allows mouse events to be
2102 bound as key bindings. See the MOUSE SUPPORT section for de‐
2103 tails.
2104 prefix key
2106 Set the key accepted as a prefix key. In addition to the stan‐
2107 dard keys described under KEY BINDINGS, prefix can be set to the
2108 special key ‘None’ to set no prefix.
2109 prefix2 key
2111 Set a secondary key accepted as a prefix key. Like prefix,
2112 prefix2 can be set to ‘None’.
2113 renumber-windows [on | off]
2115 If on, when a window is closed in a session, automatically renum‐
2116 ber the other windows in numerical order. This respects the
2117 base-index option if it has been set. If off, do not renumber
2118 the windows.
2119 repeat-time time
2121 Allow multiple commands to be entered without pressing the pre‐
2122 fix-key again in the specified time milliseconds (the default is
2123 500). Whether a key repeats may be set when it is bound using
2124 the -r flag to bind-key. Repeat is enabled for the default keys
2125 bound to the resize-pane command.
2126 set-titles [on | off]
2128 Attempt to set the client terminal title using the tsl and fsl
2129 terminfo(5) entries if they exist. tmux automatically sets these
2130 to the \e]0;...\007 sequence if the terminal appears to be
2131 xterm(1). This option is off by default.
2132 set-titles-string string
2134 String used to set the client terminal title if set-titles is on.
2135 Formats are expanded, see the FORMATS section.
2136 silence-action [any | none | current | other]
2138 Set action on window silence when monitor-silence is on. The
2139 values are the same as those for activity-action.
2140 status [off | on | 2 | 3 | 4 | 5]
2142 Show or hide the status line or specify its size. Using on gives
2143 a status line one row in height; 2, 3, 4 or 5 more rows.
2144 status-format[] format
2146 Specify the format to be used for each line of the status line.
2147 The default builds the top status line from the various individ‐
2148 ual status options below.
2149 status-interval interval
2151 Update the status line every interval seconds. By default, up‐
2152 dates will occur every 15 seconds. A setting of zero disables
2153 redrawing at interval.
2154 status-justify [left | centre | right | absolute-centre]
2156 Set the position of the window list in the status line: left,
2157 centre or right. centre puts the window list in the relative
2158 centre of the available free space; absolute-centre uses the cen‐
2159 tre of the entire horizontal space.
2160 status-keys [vi | emacs]
2162 Use vi or emacs-style key bindings in the status line, for exam‐
2163 ple at the command prompt. The default is emacs, unless the
2164 VISUAL or EDITOR environment variables are set and contain the
2165 string ‘vi’.
2166 status-left string
2168 Display string (by default the session name) to the left of the
2169 status line. string will be passed through strftime(3). Also
2170 see the FORMATS and STYLES sections.
2171 For details on how the names and titles can be set see the NAMES
2173 AND TITLES section.
2174 Examples are:
2176 #(sysctl vm.loadavg)
2178 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
2179 The default is ‘[#S] ’.
2181 status-left-length length
2183 Set the maximum length of the left component of the status line.
2184 The default is 10.
2185 status-left-style style
2187 Set the style of the left part of the status line. For how to
2188 specify style, see the STYLES section.
2189 status-position [top | bottom]
2191 Set the position of the status line.
2192 status-right string
2194 Display string to the right of the status line. By default, the
2195 current pane title in double quotes, the date and the time are
2196 shown. As with status-left, string will be passed to strftime(3)
2197 and character pairs are replaced.
2198 status-right-length length
2200 Set the maximum length of the right component of the status line.
2201 The default is 40.
2202 status-right-style style
2204 Set the style of the right part of the status line. For how to
2205 specify style, see the STYLES section.
2206 status-style style
2208 Set status line style. For how to specify style, see the STYLES
2209 section.
2210 update-environment[] variable
2212 Set list of environment variables to be copied into the session
2213 environment when a new session is created or an existing session
2214 is attached. Any variables that do not exist in the source envi‐
2215 ronment are set to be removed from the session environment (as if
2216 -r was given to the set-environment command).
2217 visual-activity [on | off | both]
2219 If on, display a message instead of sending a bell when activity
2220 occurs in a window for which the monitor-activity window option
2221 is enabled. If set to both, a bell and a message are produced.
2222 visual-bell [on | off | both]
2224 If on, a message is shown on a bell in a window for which the
2225 monitor-bell window option is enabled instead of it being passed
2226 through to the terminal (which normally makes a sound). If set
2227 to both, a bell and a message are produced. Also see the
2228 bell-action option.
2229 visual-silence [on | off | both]
2231 If monitor-silence is enabled, prints a message after the inter‐
2232 val has expired on a given window instead of sending a bell. If
2233 set to both, a bell and a message are produced.
2234 word-separators string
2236 Sets the session's conception of what characters are considered
2237 word separators, for the purposes of the next and previous word
2238 commands in copy mode.
2239 Available window options are:
2241 aggressive-resize [on | off]
2243 Aggressively resize the chosen window. This means that tmux will
2244 resize the window to the size of the smallest or largest session
2245 (see the window-size option) for which it is the current window,
2246 rather than the session to which it is attached. The window may
2247 resize when the current window is changed on another session;
2248 this option is good for full-screen programs which support
2249 SIGWINCH and poor for interactive programs such as shells.
2250 automatic-rename [on | off]
2252 Control automatic window renaming. When this setting is enabled,
2253 tmux will rename the window automatically using the format speci‐
2254 fied by automatic-rename-format. This flag is automatically dis‐
2255 abled for an individual window when a name is specified at cre‐
2256 ation with new-window or new-session, or later with
2257 rename-window, or with a terminal escape sequence. It may be
2258 switched off globally with:
2259 set-option -wg automatic-rename off
2261 automatic-rename-format format
2263 The format (see FORMATS) used when the automatic-rename option is
2264 enabled.
2265 clock-mode-colour colour
2267 Set clock colour.
2268 clock-mode-style [12 | 24]
2270 Set clock hour format.
2271 fill-character character
2273 Set the character used to fill areas of the terminal unused by a
2274 window.
2275 main-pane-height height
2277 main-pane-width width
2278 Set the width or height of the main (left or top) pane in the
2279 main-horizontal or main-vertical layouts. If suffixed by ‘%’,
2280 this is a percentage of the window size.
2281 copy-mode-match-style style
2283 Set the style of search matches in copy mode. For how to specify
2284 style, see the STYLES section.
2285 copy-mode-mark-style style
2287 Set the style of the line containing the mark in copy mode. For
2288 how to specify style, see the STYLES section.
2289 copy-mode-current-match-style style
2291 Set the style of the current search match in copy mode. For how
2292 to specify style, see the STYLES section.
2293 mode-keys [vi | emacs]
2295 Use vi or emacs-style key bindings in copy mode. The default is
2296 emacs, unless VISUAL or EDITOR contains ‘vi’.
2297 mode-style style
2299 Set window modes style. For how to specify style, see the STYLES
2300 section.
2301 monitor-activity [on | off]
2303 Monitor for activity in the window. Windows with activity are
2304 highlighted in the status line.
2305 monitor-bell [on | off]
2307 Monitor for a bell in the window. Windows with a bell are high‐
2308 lighted in the status line.
2309 monitor-silence [interval]
2311 Monitor for silence (no activity) in the window within interval
2312 seconds. Windows that have been silent for the interval are
2313 highlighted in the status line. An interval of zero disables the
2314 monitoring.
2315 other-pane-height height
2317 Set the height of the other panes (not the main pane) in the
2318 main-horizontal layout. If this option is set to 0 (the de‐
2319 fault), it will have no effect. If both the main-pane-height and
2320 other-pane-height options are set, the main pane will grow taller
2321 to make the other panes the specified height, but will never
2322 shrink to do so. If suffixed by ‘%’, this is a percentage of the
2323 window size.
2324 other-pane-width width
2326 Like other-pane-height, but set the width of other panes in the
2327 main-vertical layout.
2328 pane-active-border-style style
2330 Set the pane border style for the currently active pane. For how
2331 to specify style, see the STYLES section. Attributes are ig‐
2332 nored.
2333 pane-base-index index
2335 Like base-index, but set the starting index for pane numbers.
2336 pane-border-format format
2338 Set the text shown in pane border status lines.
2339 pane-border-indicators [off | colour | arrows | both]
2341 Indicate active pane by colouring only half of the border in win‐
2342 dows with exactly two panes, by displaying arrow markers, by
2343 drawing both or neither.
2344 pane-border-lines type
2346 Set the type of characters used for drawing pane borders. type
2347 may be one of:
2348 single single lines using ACS or UTF-8 characters
2350 double double lines using UTF-8 characters
2352 heavy heavy lines using UTF-8 characters
2354 simple simple ASCII characters
2356 number the pane number
2358 ‘double’ and ‘heavy’ will fall back to standard ACS line drawing
2360 when UTF-8 is not supported.
2361 pane-border-status [off | top | bottom]
2363 Turn pane border status lines off or set their position.
2364 pane-border-style style
2366 Set the pane border style for panes aside from the active pane.
2367 For how to specify style, see the STYLES section. Attributes are
2368 ignored.
2369 popup-style style
2371 Set the popup style. See the STYLES section on how to specify
2372 style. Attributes are ignored.
2373 popup-border-style style
2375 Set the popup border style. See the STYLES section on how to
2376 specify style. Attributes are ignored.
2377 popup-border-lines type
2379 Set the type of characters used for drawing popup borders. type
2380 may be one of:
2381 single single lines using ACS or UTF-8 characters (default)
2383 rounded
2385 variation of single with rounded corners using UTF-8
2386 characters
2387 double double lines using UTF-8 characters
2389 heavy heavy lines using UTF-8 characters
2391 simple simple ASCII characters
2393 padded simple ASCII space character
2395 none no border
2397 ‘double’ and ‘heavy’ will fall back to standard ACS line drawing
2399 when UTF-8 is not supported.
2400 window-status-activity-style style
2402 Set status line style for windows with an activity alert. For
2403 how to specify style, see the STYLES section.
2404 window-status-bell-style style
2406 Set status line style for windows with a bell alert. For how to
2407 specify style, see the STYLES section.
2408 window-status-current-format string
2410 Like window-status-format, but is the format used when the window
2411 is the current window.
2412 window-status-current-style style
2414 Set status line style for the currently active window. For how
2415 to specify style, see the STYLES section.
2416 window-status-format string
2418 Set the format in which the window is displayed in the status
2419 line window list. See the FORMATS and STYLES sections.
2420 window-status-last-style style
2422 Set status line style for the last active window. For how to
2423 specify style, see the STYLES section.
2424 window-status-separator string
2426 Sets the separator drawn between windows in the status line. The
2427 default is a single space character.
2428 window-status-style style
2430 Set status line style for a single window. For how to specify
2431 style, see the STYLES section.
2432 window-size largest | smallest | manual | latest
2434 Configure how tmux determines the window size. If set to
2435 largest, the size of the largest attached session is used; if
2436 smallest, the size of the smallest. If manual, the size of a new
2437 window is set from the default-size option and windows are re‐
2438 sized automatically. With latest, tmux uses the size of the
2439 client that had the most recent activity. See also the
2440 resize-window command and the aggressive-resize option.
2441 wrap-search [on | off]
2443 If this option is set, searches will wrap around the end of the
2444 pane contents. The default is on.
2445 Available pane options are:
2447 allow-passthrough [on | off | all]
2449 Allow programs in the pane to bypass tmux using a terminal escape
2450 sequence (\ePtmux;...\e\\). If set to on, passthrough sequences
2451 will be allowed only if the pane is visible. If set to all, they
2452 will be allowed even if the pane is invisible.
2453 allow-rename [on | off]
2455 Allow programs in the pane to change the window name using a ter‐
2456 minal escape sequence (\ek...\e\\).
2457 alternate-screen [on | off]
2459 This option configures whether programs running inside the pane
2460 may use the terminal alternate screen feature, which allows the
2461 smcup and rmcup terminfo(5) capabilities. The alternate screen
2462 feature preserves the contents of the window when an interactive
2463 application starts and restores it on exit, so that any output
2464 visible before the application starts reappears unchanged after
2465 it exits.
2466 cursor-colour colour
2468 Set the colour of the cursor.
2469 pane-colours[] colour
2471 The default colour palette. Each entry in the array defines the
2472 colour tmux uses when the colour with that index is requested.
2473 The index may be from zero to 255.
2474 cursor-style style
2476 Set the style of the cursor. Available styles are: default,
2477 blinking-block, block, blinking-underline, underline,
2478 blinking-bar, bar.
2479 remain-on-exit [on | off | failed]
2481 A pane with this flag set is not destroyed when the program run‐
2482 ning in it exits. If set to failed, then only when the program
2483 exit status is not zero. The pane may be reactivated with the
2484 respawn-pane command.
2485 remain-on-exit-format string
2487 Set the text shown at the bottom of exited panes when
2488 remain-on-exit is enabled.
2489 scroll-on-clear [on | off]
2491 When the entire screen is cleared and this option is on, scroll
2492 the contents of the screen into history before clearing it.
2493 synchronize-panes [on | off]
2495 Duplicate input to all other panes in the same window where this
2496 option is also on (only for panes that are not in any mode).
2497 window-active-style style
2499 Set the pane style when it is the active pane. For how to spec‐
2500 ify style, see the STYLES section.
2501 window-style style
2503 Set the pane style. For how to specify style, see the STYLES
2504 section.
2505
2507 tmux allows commands to run on various triggers, called hooks. Most tmux
2508 commands have an after hook and there are a number of hooks not associ‐
2509 ated with commands.
2510 Hooks are stored as array options, members of the array are executed in
2512 order when the hook is triggered. Like options different hooks may be
2513 global or belong to a session, window or pane. Hooks may be configured
2514 with the set-hook or set-option commands and displayed with show-hooks or
2515 show-options -H. The following two commands are equivalent:
2516 set-hook -g pane-mode-changed[42] 'set -g status-left-style bg=red'
2518 set-option -g pane-mode-changed[42] 'set -g status-left-style bg=red'
2519 Setting a hook without specifying an array index clears the hook and sets
2521 the first member of the array.
2522 A command's after hook is run after it completes, except when the command
2524 is run as part of a hook itself. They are named with an ‘after-’ prefix.
2525 For example, the following command adds a hook to select the even-verti‐
2526 cal layout after every split-window:
2527 set-hook -g after-split-window "selectl even-vertical"
2529 All the notifications listed in the CONTROL MODE section are hooks (with‐
2531 out any arguments), except %exit. The following additional hooks are
2532 available:
2533 alert-activity Run when a window has activity. See
2535 monitor-activity.
2536 alert-bell Run when a window has received a bell. See
2538 monitor-bell.
2539 alert-silence Run when a window has been silent. See
2541 monitor-silence.
2542 client-active Run when a client becomes the latest active
2544 client of its session.
2545 client-attached Run when a client is attached.
2547 client-detached Run when a client is detached
2549 client-focus-in Run when focus enters a client
2551 client-focus-out Run when focus exits a client
2553 client-resized Run when a client is resized.
2555 client-session-changed Run when a client's attached session is changed.
2557 pane-died Run when the program running in a pane exits, but
2559 remain-on-exit is on so the pane has not closed.
2560 pane-exited Run when the program running in a pane exits.
2562 pane-focus-in Run when the focus enters a pane, if the
2564 focus-events option is on.
2565 pane-focus-out Run when the focus exits a pane, if the
2567 focus-events option is on.
2568 pane-set-clipboard Run when the terminal clipboard is set using the
2570 xterm(1) escape sequence.
2571 session-created Run when a new session created.
2573 session-closed Run when a session closed.
2575 session-renamed Run when a session is renamed.
2577 window-linked Run when a window is linked into a session.
2579 window-renamed Run when a window is renamed.
2581 window-resized Run when a window is resized. This may be after
2583 the client-resized hook is run.
2584 window-unlinked Run when a window is unlinked from a session.
2586 Hooks are managed with these commands:
2588 set-hook [-agpRuw] [-t target-pane] hook-name command
2590 Without -R, sets (or with -u unsets) hook hook-name to command.
2591 The flags are the same as for set-option.
2592 With -R, run hook-name immediately.
2594 show-hooks [-gpw] [-t target-pane]
2596 Shows hooks. The flags are the same as for show-options.
2597
2599 If the mouse option is on (the default is off), tmux allows mouse events
2600 to be bound as keys. The name of each key is made up of a mouse event
2601 (such as ‘MouseUp1’) and a location suffix, one of the following:
2602 Pane the contents of a pane
2604 Border a pane border
2605 Status the status line window list
2606 StatusLeft the left part of the status line
2607 StatusRight the right part of the status line
2608 StatusDefault any other part of the status line
2609 The following mouse events are available:
2611 WheelUp WheelDown
2613 MouseDown1 MouseUp1 MouseDrag1 MouseDragEnd1
2614 MouseDown2 MouseUp2 MouseDrag2 MouseDragEnd2
2615 MouseDown3 MouseUp3 MouseDrag3 MouseDragEnd3
2616 SecondClick1 SecondClick2 SecondClick3
2617 DoubleClick1 DoubleClick2 DoubleClick3
2618 TripleClick1 TripleClick2 TripleClick3
2619 The ‘SecondClick’ events are fired for the second click of a double
2621 click, even if there may be a third click which will fire ‘TripleClick’
2622 instead of ‘DoubleClick’.
2623 Each should be suffixed with a location, for example ‘MouseDown1Status’.
2625 The special token ‘{mouse}’ or ‘=’ may be used as target-window or
2627 target-pane in commands bound to mouse key bindings. It resolves to the
2628 window or pane over which the mouse event took place (for example, the
2629 window in the status line over which button 1 was released for a
2630 ‘MouseUp1Status’ binding, or the pane over which the wheel was scrolled
2631 for a ‘WheelDownPane’ binding).
2632 The send-keys -M flag may be used to forward a mouse event to a pane.
2634 The default key bindings allow the mouse to be used to select and resize
2636 panes, to copy text and to change window using the status line. These
2637 take effect if the mouse option is turned on.
2638
2640 Certain commands accept the -F flag with a format argument. This is a
2641 string which controls the output format of the command. Format variables
2642 are enclosed in ‘#{’ and ‘}’, for example ‘#{session_name}’. The possi‐
2643 ble variables are listed in the table below, or the name of a tmux option
2644 may be used for an option's value. Some variables have a shorter alias
2645 such as ‘#S’; ‘##’ is replaced by a single ‘#’, ‘#,’ by a ‘,’ and ‘#}’ by
2646 a ‘}’.
2647 Conditionals are available by prefixing with ‘?’ and separating two al‐
2649 ternatives with a comma; if the specified variable exists and is not
2650 zero, the first alternative is chosen, otherwise the second is used. For
2651 example ‘#{?session_attached,attached,not attached}’ will include the
2652 string ‘attached’ if the session is attached and the string ‘not
2653 attached’ if it is unattached, or ‘#{?automatic-rename,yes,no}’ will in‐
2654 clude ‘yes’ if automatic-rename is enabled, or ‘no’ if not. Conditionals
2655 can be nested arbitrarily. Inside a conditional, ‘,’ and ‘}’ must be es‐
2656 caped as ‘#,’ and ‘#}’, unless they are part of a ‘#{...}’ replacement.
2657 For example:
2658 #{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W .
2660 String comparisons may be expressed by prefixing two comma-separated al‐
2662 ternatives by ‘==’, ‘!=’, ‘<’, ‘>’, ‘<=’ or ‘>=’ and a colon. For exam‐
2663 ple ‘#{==:#{host},myhost}’ will be replaced by ‘1’ if running on
2664 ‘myhost’, otherwise by ‘0’. ‘||’ and ‘&&’ evaluate to true if either or
2665 both of two comma-separated alternatives are true, for example
2666 ‘#{||:#{pane_in_mode},#{alternate_on}}’.
2667 An ‘m’ specifies an fnmatch(3) or regular expression comparison. The
2669 first argument is the pattern and the second the string to compare. An
2670 optional argument specifies flags: ‘r’ means the pattern is a regular ex‐
2671 pression instead of the default fnmatch(3) pattern, and ‘i’ means to ig‐
2672 nore case. For example: ‘#{m:*foo*,#{host}}’ or ‘#{m/ri:^A,MYVAR}’. A
2673 ‘C’ performs a search for an fnmatch(3) pattern or regular expression in
2674 the pane content and evaluates to zero if not found, or a line number if
2675 found. Like ‘m’, an ‘r’ flag means search for a regular expression and
2676 ‘i’ ignores case. For example: ‘#{C/r:^Start}’
2677 Numeric operators may be performed by prefixing two comma-separated al‐
2679 ternatives with an ‘e’ and an operator. An optional ‘f’ flag may be
2680 given after the operator to use floating point numbers, otherwise inte‐
2681 gers are used. This may be followed by a number giving the number of
2682 decimal places to use for the result. The available operators are: addi‐
2683 tion ‘+’, subtraction ‘-’, multiplication ‘*’, division ‘/’, modulus ‘m’
2684 or ‘%’ (note that ‘%’ must be escaped as ‘%%’ in formats which are also
2685 expanded by strftime(3)) and numeric comparison operators ‘==’, ‘!=’,
2686 ‘<’, ‘<=’, ‘>’ and ‘>=’. For example, ‘#{e|*|f|4:5.5,3}’ multiplies 5.5
2687 by 3 for a result with four decimal places and ‘#{e|%%:7,3}’ returns the
2688 modulus of 7 and 3. ‘a’ replaces a numeric argument by its ASCII equiva‐
2689 lent, so ‘#{a:98}’ results in ‘b’. ‘c’ replaces a tmux colour by its
2690 six-digit hexadecimal RGB value.
2691 A limit may be placed on the length of the resultant string by prefixing
2693 it by an ‘=’, a number and a colon. Positive numbers count from the
2694 start of the string and negative from the end, so ‘#{=5:pane_title}’ will
2695 include at most the first five characters of the pane title, or
2696 ‘#{=-5:pane_title}’ the last five characters. A suffix or prefix may be
2697 given as a second argument - if provided then it is appended or prepended
2698 to the string if the length has been trimmed, for example
2699 ‘#{=/5/...:pane_title}’ will append ‘...’ if the pane title is more than
2700 five characters. Similarly, ‘p’ pads the string to a given width, for
2701 example ‘#{p10:pane_title}’ will result in a width of at least 10 charac‐
2702 ters. A positive width pads on the left, a negative on the right. ‘n’
2703 expands to the length of the variable and ‘w’ to its width when dis‐
2704 played, for example ‘#{n:window_name}’.
2705 Prefixing a time variable with ‘t:’ will convert it to a string, so if
2707 ‘#{window_activity}’ gives ‘1445765102’, ‘#{t:window_activity}’ gives
2708 ‘Sun Oct 25 09:25:02 2015’. Adding ‘p (’ ‘`t/p`’) will use shorter but
2709 less accurate time format for times in the past. A custom format may be
2710 given using an ‘f’ suffix (note that ‘%’ must be escaped as ‘%%’ if the
2711 format is separately being passed through strftime(3), for example in the
2712 status-left option): ‘#{t/f/%%H#:%%M:window_activity}’, see strftime(3).
2713 The ‘b:’ and ‘d:’ prefixes are basename(3) and dirname(3) of the variable
2715 respectively. ‘q:’ will escape sh(1) special characters or with a ‘h’
2716 suffix, escape hash characters (so ‘#’ becomes ‘##’). ‘E:’ will expand
2717 the format twice, for example ‘#{E:status-left}’ is the result of expand‐
2718 ing the content of the status-left option rather than the option itself.
2719 ‘T:’ is like ‘E:’ but also expands strftime(3) specifiers. ‘S:’, ‘W:’,
2720 ‘P:’ or ‘L:’ will loop over each session, window, pane or client and in‐
2721 sert the format once for each. For windows and panes, two comma-sepa‐
2722 rated formats may be given: the second is used for the current window or
2723 active pane. For example, to get a list of windows formatted like the
2724 status line:
2725 #{W:#{E:window-status-format} ,#{E:window-status-current-format} }
2727 ‘N:’ checks if a window (without any suffix or with the ‘w’ suffix) or a
2729 session (with the ‘s’ suffix) name exists, for example ‘`N/w:foo`’ is re‐
2730 placed with 1 if a window named ‘foo’ exists.
2731 A prefix of the form ‘s/foo/bar/:’ will substitute ‘foo’ with ‘bar’
2733 throughout. The first argument may be an extended regular expression and
2734 a final argument may be ‘i’ to ignore case, for example ‘s/a(.)/\1x/i:’
2735 would change ‘abABab’ into ‘bxBxbx’. A different delimiter character may
2736 also be used, to avoid collisions with literal slashes in the pattern.
2737 For example, ‘s|foo/|bar/|:’ will substitute ‘foo/’ with ‘bar/’ through‐
2738 out.
2739 In addition, the last line of a shell command's output may be inserted
2741 using ‘#()’. For example, ‘#(uptime)’ will insert the system's uptime.
2742 When constructing formats, tmux does not wait for ‘#()’ commands to fin‐
2743 ish; instead, the previous result from running the same command is used,
2744 or a placeholder if the command has not been run before. If the command
2745 hasn't exited, the most recent line of output will be used, but the sta‐
2746 tus line will not be updated more than once a second. Commands are exe‐
2747 cuted using /bin/sh and with the tmux global environment set (see the
2748 GLOBAL AND SESSION ENVIRONMENT section).
2749 An ‘l’ specifies that a string should be interpreted literally and not
2751 expanded. For example ‘#{l:#{?pane_in_mode,yes,no}}’ will be replaced by
2752 ‘#{?pane_in_mode,yes,no}’.
2753 The following variables are available, where appropriate:
2755 Variable name Alias Replaced with
2757 active_window_index Index of active window in session
2758 alternate_on 1 if pane is in alternate screen
2759 alternate_saved_x Saved cursor X in alternate screen
2760 alternate_saved_y Saved cursor Y in alternate screen
2761 buffer_created Time buffer created
2762 buffer_name Name of buffer
2763 buffer_sample Sample of start of buffer
2764 buffer_size Size of the specified buffer in bytes
2765 client_activity Time client last had activity
2766 client_cell_height Height of each client cell in pixels
2767 client_cell_width Width of each client cell in pixels
2768 client_control_mode 1 if client is in control mode
2769 client_created Time client created
2770 client_discarded Bytes discarded when client behind
2771 client_flags List of client flags
2772 client_height Height of client
2773 client_key_table Current key table
2774 client_last_session Name of the client's last session
2775 client_name Name of client
2776 client_pid PID of client process
2777 client_prefix 1 if prefix key has been pressed
2778 client_readonly 1 if client is read-only
2779 client_session Name of the client's session
2780 client_termfeatures Terminal features of client, if any
2781 client_termname Terminal name of client
2782 client_termtype Terminal type of client, if available
2783 client_tty Pseudo terminal of client
2784 client_uid UID of client process
2785 client_user User of client process
2786 client_utf8 1 if client supports UTF-8
2787 client_width Width of client
2788 client_written Bytes written to client
2789 command Name of command in use, if any
2790 command_list_alias Command alias if listing commands
2791 command_list_name Command name if listing commands
2792 command_list_usage Command usage if listing commands
2793 config_files List of configuration files loaded
2794 copy_cursor_line Line the cursor is on in copy mode
2795 copy_cursor_word Word under cursor in copy mode
2796 copy_cursor_x Cursor X position in copy mode
2797 copy_cursor_y Cursor Y position in copy mode
2798 current_file Current configuration file
2799 cursor_character Character at cursor in pane
2800 cursor_flag Pane cursor flag
2801 cursor_x Cursor X position in pane
2802 cursor_y Cursor Y position in pane
2803 history_bytes Number of bytes in window history
2804 history_limit Maximum window history lines
2805 history_size Size of history in lines
2806 hook Name of running hook, if any
2807 hook_client Name of client where hook was run, if any
2808 hook_pane ID of pane where hook was run, if any
2809 hook_session ID of session where hook was run, if any
2810 hook_session_name Name of session where hook was run, if
2811 any
2812 hook_window ID of window where hook was run, if any
2813 hook_window_name Name of window where hook was run, if any
2814 host #H Hostname of local host
2815 host_short #h Hostname of local host (no domain name)
2816 insert_flag Pane insert flag
2817 keypad_cursor_flag Pane keypad cursor flag
2818 keypad_flag Pane keypad flag
2819 last_window_index Index of last window in session
2820 line Line number in the list
2821 mouse_all_flag Pane mouse all flag
2822 mouse_any_flag Pane mouse any flag
2823 mouse_button_flag Pane mouse button flag
2824 mouse_hyperlink Hyperlink under mouse, if any
2825 mouse_line Line under mouse, if any
2826 mouse_sgr_flag Pane mouse SGR flag
2827 mouse_standard_flag Pane mouse standard flag
2828 mouse_status_line Status line on which mouse event took
2829 place
2830 mouse_status_range Range type or argument of mouse event on
2831 status line
2832 mouse_utf8_flag Pane mouse UTF-8 flag
2833 mouse_word Word under mouse, if any
2834 mouse_x Mouse X position, if any
2835 mouse_y Mouse Y position, if any
2836 next_session_id Unique session ID for next new session
2837 origin_flag Pane origin flag
2838 pane_active 1 if active pane
2839 pane_at_bottom 1 if pane is at the bottom of window
2840 pane_at_left 1 if pane is at the left of window
2841 pane_at_right 1 if pane is at the right of window
2842 pane_at_top 1 if pane is at the top of window
2843 pane_bg Pane background colour
2844 pane_bottom Bottom of pane
2845 pane_current_command Current command if available
2846 pane_current_path Current path if available
2847 pane_dead 1 if pane is dead
2848 pane_dead_signal Exit signal of process in dead pane
2849 pane_dead_status Exit status of process in dead pane
2850 pane_dead_time Exit time of process in dead pane
2851 pane_fg Pane foreground colour
2852 pane_format 1 if format is for a pane
2853 pane_height Height of pane
2854 pane_id #D Unique pane ID
2855 pane_in_mode 1 if pane is in a mode
2856 pane_index #P Index of pane
2857 pane_input_off 1 if input to pane is disabled
2858 pane_last 1 if last pane
2859 pane_left Left of pane
2860 pane_marked 1 if this is the marked pane
2861 pane_marked_set 1 if a marked pane is set
2862 pane_mode Name of pane mode, if any
2863 pane_path Path of pane (can be set by application)
2864 pane_pid PID of first process in pane
2865 pane_pipe 1 if pane is being piped
2866 pane_right Right of pane
2867 pane_search_string Last search string in copy mode
2868 pane_start_command Command pane started with
2869 pane_start_path Path pane started with
2870 pane_synchronized 1 if pane is synchronized
2871 pane_tabs Pane tab positions
2872 pane_title #T Title of pane (can be set by application)
2873 pane_top Top of pane
2874 pane_tty Pseudo terminal of pane
2875 pane_unseen_changes 1 if there were changes in pane while in
2876 mode
2877 pane_width Width of pane
2878 pid Server PID
2879 rectangle_toggle 1 if rectangle selection is activated
2880 scroll_position Scroll position in copy mode
2881 scroll_region_lower Bottom of scroll region in pane
2882 scroll_region_upper Top of scroll region in pane
2883 search_match Search match if any
2884 search_present 1 if search started in copy mode
2885 selection_active 1 if selection started and changes with
2886 the cursor in copy mode
2887 selection_end_x X position of the end of the selection
2888 selection_end_y Y position of the end of the selection
2889 selection_present 1 if selection started in copy mode
2890 selection_start_x X position of the start of the selection
2891 selection_start_y Y position of the start of the selection
2892 server_sessions Number of sessions
2893 session_activity Time of session last activity
2894 session_alerts List of window indexes with alerts
2895 session_attached Number of clients session is attached to
2896 session_attached_list List of clients session is attached to
2897 session_created Time session created
2898 session_format 1 if format is for a session
2899 session_group Name of session group
2900 session_group_attached Number of clients sessions in group are
2901 attached to
2902 session_group_attached_list List of clients sessions in group are
2903 attached to
2904 session_group_list List of sessions in group
2905 session_group_many_attached 1 if multiple clients attached to
2906 sessions in group
2907 session_group_size Size of session group
2908 session_grouped 1 if session in a group
2909 session_id Unique session ID
2910 session_last_attached Time session last attached
2911 session_many_attached 1 if multiple clients attached
2912 session_marked 1 if this session contains the marked
2913 pane
2914 session_name #S Name of session
2915 session_path Working directory of session
2916 session_stack Window indexes in most recent order
2917 session_windows Number of windows in session
2918 socket_path Server socket path
2919 start_time Server start time
2920 uid Server UID
2921 user Server user
2922 version Server version
2923 window_active 1 if window active
2924 window_active_clients Number of clients viewing this window
2925 window_active_clients_list List of clients viewing this window
2926 window_active_sessions Number of sessions on which this window
2927 is active
2928 window_active_sessions_list List of sessions on which this window is
2929 active
2930 window_activity Time of window last activity
2931 window_activity_flag 1 if window has activity
2932 window_bell_flag 1 if window has bell
2933 window_bigger 1 if window is larger than client
2934 window_cell_height Height of each cell in pixels
2935 window_cell_width Width of each cell in pixels
2936 window_end_flag 1 if window has the highest index
2937 window_flags #F Window flags with # escaped as ##
2938 window_format 1 if format is for a window
2939 window_height Height of window
2940 window_id Unique window ID
2941 window_index #I Index of window
2942 window_last_flag 1 if window is the last used
2943 window_layout Window layout description, ignoring
2944 zoomed window panes
2945 window_linked 1 if window is linked across sessions
2946 window_linked_sessions Number of sessions this window is linked
2947 to
2948 window_linked_sessions_list List of sessions this window is linked to
2949 window_marked_flag 1 if window contains the marked pane
2950 window_name #W Name of window
2951 window_offset_x X offset into window if larger than
2952 client
2953 window_offset_y Y offset into window if larger than
2954 client
2955 window_panes Number of panes in window
2956 window_raw_flags Window flags with nothing escaped
2957 window_silence_flag 1 if window has silence alert
2958 window_stack_index Index in session most recent stack
2959 window_start_flag 1 if window has the lowest index
2960 window_visible_layout Window layout description, respecting
2961 zoomed window panes
2962 window_width Width of window
2963 window_zoomed_flag 1 if window is zoomed
2964 wrap_flag Pane wrap flag
2965
2967 tmux offers various options to specify the colour and attributes of as‐
2968 pects of the interface, for example status-style for the status line. In
2969 addition, embedded styles may be specified in format options, such as
2970 status-left, by enclosing them in ‘#[’ and ‘]’.
2971 A style may be the single term ‘default’ to specify the default style
2973 (which may come from an option, for example status-style in the status
2974 line) or a space or comma separated list of the following:
2975 fg=colour
2977 Set the foreground colour. The colour is one of: black, red,
2978 green, yellow, blue, magenta, cyan, white; if supported the
2979 bright variants brightred, brightgreen, brightyellow; colour0 to
2980 colour255 from the 256-colour set; default for the default
2981 colour; terminal for the terminal default colour; or a hexadeci‐
2982 mal RGB string such as ‘#ffffff’.
2983 bg=colour
2985 Set the background colour.
2986 us=colour
2988 Set the underscore colour.
2989 none Set no attributes (turn off any active attributes).
2991 acs, bright (or bold), dim, underscore, blink, reverse, hidden, italics,
2993 overline, strikethrough, double-underscore, curly-underscore,
2994 dotted-underscore, dashed-underscore
2995 Set an attribute. Any of the attributes may be prefixed with
2996 ‘no’ to unset. acs is the terminal alternate character set.
2997 align=left (or noalign), align=centre, align=right
2999 Align text to the left, centre or right of the available space if
3000 appropriate.
3001 fill=colour
3003 Fill the available space with a background colour if appropriate.
3004 list=on, list=focus, list=left-marker, list=right-marker, nolist
3006 Mark the position of the various window list components in the
3007 status-format option: list=on marks the start of the list;
3008 list=focus is the part of the list that should be kept in focus
3009 if the entire list won't fit in the available space (typically
3010 the current window); list=left-marker and list=right-marker mark
3011 the text to be used to mark that text has been trimmed from the
3012 left or right of the list if there is not enough space.
3013 push-default, pop-default
3015 Store the current colours and attributes as the default or reset
3016 to the previous default. A push-default affects any subsequent
3017 use of the default term until a pop-default. Only one default
3018 may be pushed (each push-default replaces the previous saved de‐
3019 fault).
3020 range=left, range=right, range=session|X, range=window|X, range=pane|X,
3022 range=user|X, norange
3023 Mark a range for mouse events in the status-format option. When
3024 a mouse event occurs in the range=left or range=right range, the
3025 ‘StatusLeft’ and ‘StatusRight’ key bindings are triggered.
3026 range=session|X, range=window|X and range=pane|X are ranges for a
3028 session, window or pane. These trigger the ‘Status’ mouse key
3029 with the target session, window or pane given by the ‘X’ argu‐
3030 ment. ‘X’ is a session ID, window index in the current session
3031 or a pane ID. For these, the mouse_status_range format variable
3032 will be set to ‘session’, ‘window’ or ‘pane’.
3033 range=user|X is a user-defined range; it triggers the ‘Status’
3035 mouse key. The argument ‘X’ will be available in the
3036 mouse_status_range format variable. ‘X’ must be at most 15 bytes
3037 in length.
3038 Examples are:
3040 fg=yellow bold underscore blink
3042 bg=black,fg=default,noreverse
3043
3045 tmux distinguishes between names and titles. Windows and sessions have
3046 names, which may be used to specify them in targets and are displayed in
3047 the status line and various lists: the name is the tmux identifier for a
3048 window or session. Only panes have titles. A pane's title is typically
3049 set by the program running inside the pane using an escape sequence (like
3050 it would set the xterm(1) window title in X(7)). Windows themselves do
3051 not have titles - a window's title is the title of its active pane. tmux
3052 itself may set the title of the terminal in which the client is running,
3053 see the set-titles option.
3054 A session's name is set with the new-session and rename-session commands.
3056 A window's name is set with one of:
3057 1. A command argument (such as -n for new-window or new-session).
3059 2. An escape sequence (if the allow-rename option is turned on):
3061 $ printf '\033kWINDOW_NAME\033\\'
3063 3. Automatic renaming, which sets the name to the active command in
3065 the window's active pane. See the automatic-rename option.
3066 When a pane is first created, its title is the hostname. A pane's title
3068 can be set via the title setting escape sequence, for example:
3069 $ printf '\033]2;My Title\033\\'
3071 It can also be modified with the select-pane -T command.
3073
3075 When the server is started, tmux copies the environment into the global
3076 environment; in addition, each session has a session environment. When a
3077 window is created, the session and global environments are merged. If a
3078 variable exists in both, the value from the session environment is used.
3079 The result is the initial environment passed to the new process.
3080 The update-environment session option may be used to update the session
3082 environment from the client when a new session is created or an old reat‐
3083 tached. tmux also initialises the TMUX variable with some internal in‐
3084 formation to allow commands to be executed from inside, and the TERM
3085 variable with the correct terminal setting of ‘screen’.
3086 Variables in both session and global environments may be marked as hid‐
3088 den. Hidden variables are not passed into the environment of new pro‐
3089 cesses and instead can only be used by tmux itself (for example in for‐
3090 mats, see the FORMATS section).
3091 Commands to alter and view the environment are:
3093 set-environment [-Fhgru] [-t target-session] name [value]
3095 (alias: setenv)
3096 Set or unset an environment variable. If -g is used, the change
3097 is made in the global environment; otherwise, it is applied to
3098 the session environment for target-session. If -F is present,
3099 then value is expanded as a format. The -u flag unsets a vari‐
3100 able. -r indicates the variable is to be removed from the envi‐
3101 ronment before starting a new process. -h marks the variable as
3102 hidden.
3103 show-environment [-hgs] [-t target-session] [variable]
3105 (alias: showenv)
3106 Display the environment for target-session or the global environ‐
3107 ment with -g. If variable is omitted, all variables are shown.
3108 Variables removed from the environment are prefixed with ‘-’. If
3109 -s is used, the output is formatted as a set of Bourne shell com‐
3110 mands. -h shows hidden variables (omitted by default).
3111
3113 tmux includes an optional status line which is displayed in the bottom
3114 line of each terminal.
3115 By default, the status line is enabled and one line in height (it may be
3117 disabled or made multiple lines with the status session option) and con‐
3118 tains, from left-to-right: the name of the current session in square
3119 brackets; the window list; the title of the active pane in double quotes;
3120 and the time and date.
3121 Each line of the status line is configured with the status-format option.
3123 The default is made of three parts: configurable left and right sections
3124 (which may contain dynamic content such as the time or output from a
3125 shell command, see the status-left, status-left-length, status-right, and
3126 status-right-length options below), and a central window list. By de‐
3127 fault, the window list shows the index, name and (if any) flag of the
3128 windows present in the current session in ascending numerical order. It
3129 may be customised with the window-status-format and
3130 window-status-current-format options. The flag is one of the following
3131 symbols appended to the window name:
3132 Symbol Meaning
3134 * Denotes the current window.
3135 - Marks the last window (previously selected).
3136 # Window activity is monitored and activity has been
3137 detected.
3138 ! Window bells are monitored and a bell has occurred in the
3139 window.
3140 ~ The window has been silent for the monitor-silence
3141 interval.
3142 M The window contains the marked pane.
3143 Z The window's active pane is zoomed.
3144 The # symbol relates to the monitor-activity window option. The window
3146 name is printed in inverted colours if an alert (bell, activity or si‐
3147 lence) is present.
3148 The colour and attributes of the status line may be configured, the en‐
3150 tire status line using the status-style session option and individual
3151 windows using the window-status-style window option.
3152 The status line is automatically refreshed at interval if it has changed,
3154 the interval may be controlled with the status-interval session option.
3155 Commands related to the status line are as follows:
3157 clear-prompt-history [-T prompt-type]
3159 (alias: clearphist)
3160 Clear status prompt history for prompt type prompt-type. If -T
3161 is omitted, then clear history for all types. See command-prompt
3162 for possible values for prompt-type.
3163 command-prompt [-1bFikN] [-I inputs] [-p prompts] [-t target-client] [-T
3165 prompt-type] [template]
3166 Open the command prompt in a client. This may be used from in‐
3167 side tmux to execute commands interactively.
3168 If template is specified, it is used as the command. With -F,
3170 template is expanded as a format.
3171 If present, -I is a comma-separated list of the initial text for
3173 each prompt. If -p is given, prompts is a comma-separated list
3174 of prompts which are displayed in order; otherwise a single
3175 prompt is displayed, constructed from template if it is present,
3176 or ‘:’ if not.
3177 Before the command is executed, the first occurrence of the
3179 string ‘%%’ and all occurrences of ‘%1’ are replaced by the re‐
3180 sponse to the first prompt, all ‘%2’ are replaced with the re‐
3181 sponse to the second prompt, and so on for further prompts. Up
3182 to nine prompt responses may be replaced (‘%1’ to ‘%9’). ‘%%%’
3183 is like ‘%%’ but any quotation marks are escaped.
3184 -1 makes the prompt only accept one key press, in this case the
3186 resulting input is a single character. -k is like -1 but the key
3187 press is translated to a key name. -N makes the prompt only ac‐
3188 cept numeric key presses. -i executes the command every time the
3189 prompt input changes instead of when the user exits the command
3190 prompt.
3191 -T tells tmux the prompt type. This affects what completions are
3193 offered when Tab is pressed. Available types are: ‘command’,
3194 ‘search’, ‘target’ and ‘window-target’.
3195 The following keys have a special meaning in the command prompt,
3197 depending on the value of the status-keys option:
3198 Function vi emacs
3200 Cancel command prompt q Escape
3201 Delete from cursor to start of word C-w
3202 Delete entire command d C-u
3203 Delete from cursor to end D C-k
3204 Execute command Enter Enter
3205 Get next command from history Down
3206 Get previous command from history Up
3207 Insert top paste buffer p C-y
3208 Look for completions Tab Tab
3209 Move cursor left h Left
3210 Move cursor right l Right
3211 Move cursor to end $ C-e
3212 Move cursor to next word w M-f
3213 Move cursor to previous word b M-b
3214 Move cursor to start 0 C-a
3215 Transpose characters C-t
3216 With -b, the prompt is shown in the background and the invoking
3218 client does not exit until it is dismissed.
3219 confirm-before [-by] [-c confirm-key] [-p prompt] [-t target-client]
3221 command
3222 (alias: confirm)
3223 Ask for confirmation before executing command. If -p is given,
3224 prompt is the prompt to display; otherwise a prompt is construc‐
3225 ted from command. It may contain the special character sequences
3226 supported by the status-left option. With -b, the prompt is
3227 shown in the background and the invoking client does not exit un‐
3228 til it is dismissed. -y changes the default behaviour (if Enter
3229 alone is pressed) of the prompt to run the command. -c changes
3230 the confirmation key to confirm-key; the default is ‘y’.
3231 display-menu [-O] [-b border-lines] [-c target-client] [-C
3233 starting-choice] [-H selected-style] [-s style] [-S border-style]
3234 [-t target-pane] [-T title] [-x position] [-y position] name key
3235 command [argument ...]
3236 (alias: menu)
3237 Display a menu on target-client. target-pane gives the target
3238 for any commands run from the menu.
3239 A menu is passed as a series of arguments: first the menu item
3241 name, second the key shortcut (or empty for none) and third the
3242 command to run when the menu item is chosen. The name and com‐
3243 mand are formats, see the FORMATS and STYLES sections. If the
3244 name begins with a hyphen (-), then the item is disabled (shown
3245 dim) and may not be chosen. The name may be empty for a separa‐
3246 tor line, in which case both the key and command should be omit‐
3247 ted.
3248 -b sets the type of characters used for drawing menu borders.
3250 See popup-border-lines for possible values for border-lines.
3251 -H sets the style for the selected menu item (see STYLES).
3253 -s sets the style for the menu and -S sets the style for the menu
3255 border (see STYLES).
3256 -T is a format for the menu title (see FORMATS).
3258 -C sets the menu item selected by default, if the menu is not
3260 bound to a mouse key binding.
3261 -x and -y give the position of the menu. Both may be a row or
3263 column number, or one of the following special values:
3264 Value Flag Meaning
3266 C Both The centre of the terminal
3267 R -x The right side of the terminal
3268 P Both The bottom left of the pane
3269 M Both The mouse position
3270 W Both The window position on the status line
3271 S -y The line above or below the status line
3272 Or a format, which is expanded including the following additional
3274 variables:
3275 Variable name Replaced with
3277 popup_centre_x Centered in the client
3278 popup_centre_y Centered in the client
3279 popup_height Height of menu or popup
3280 popup_mouse_bottom Bottom of at the mouse
3281 popup_mouse_centre_x Horizontal centre at the
3282 mouse
3283 popup_mouse_centre_y Vertical centre at the mouse
3284 popup_mouse_top Top at the mouse
3285 popup_mouse_x Mouse X position
3286 popup_mouse_y Mouse Y position
3287 popup_pane_bottom Bottom of the pane
3288 popup_pane_left Left of the pane
3289 popup_pane_right Right of the pane
3290 popup_pane_top Top of the pane
3291 popup_status_line_y Above or below the status
3292 line
3293 popup_width Width of menu or popup
3294 popup_window_status_line_x At the window position in
3295 status line
3296 popup_window_status_line_y At the status line showing
3297 the window
3298 Each menu consists of items followed by a key shortcut shown in
3300 brackets. If the menu is too large to fit on the terminal, it is
3301 not displayed. Pressing the key shortcut chooses the correspond‐
3302 ing item. If the mouse is enabled and the menu is opened from a
3303 mouse key binding, releasing the mouse button with an item se‐
3304 lected chooses that item and releasing the mouse button without
3305 an item selected closes the menu. -O changes this behaviour so
3306 that the menu does not close when the mouse button is released
3307 without an item selected the menu is not closed and a mouse but‐
3308 ton must be clicked to choose an item.
3309 The following keys are also available:
3311 Key Function
3313 Enter Choose selected item
3314 Up Select previous item
3315 Down Select next item
3316 q Exit menu
3317 display-message [-aIlNpv] [-c target-client] [-d delay] [-t target-pane]
3319 [message]
3320 (alias: display)
3321 Display a message. If -p is given, the output is printed to std‐
3322 out, otherwise it is displayed in the target-client status line
3323 for up to delay milliseconds. If delay is not given, the
3324 display-time option is used; a delay of zero waits for a key
3325 press. ‘N’ ignores key presses and closes only after the delay
3326 expires. If -l is given, message is printed unchanged. Other‐
3327 wise, the format of message is described in the FORMATS section;
3328 information is taken from target-pane if -t is given, otherwise
3329 the active pane.
3330 -v prints verbose logging as the format is parsed and -a lists
3332 the format variables and their values.
3333 -I forwards any input read from stdin to the empty pane given by
3335 target-pane.
3336 display-popup [-BCE] [-b border-lines] [-c target-client] [-d
3338 start-directory] [-e environment] [-h height] [-s border-style]
3339 [-S style] [-t target-pane] [-T title] [-w width] [-x position]
3340 [-y position] [shell-command]
3341 (alias: popup)
3342 Display a popup running shell-command on target-client. A popup
3343 is a rectangular box drawn over the top of any panes. Panes are
3344 not updated while a popup is present.
3345 -E closes the popup automatically when shell-command exits. Two
3347 -E closes the popup only if shell-command exited with success.
3348 -x and -y give the position of the popup, they have the same
3350 meaning as for the display-menu command. -w and -h give the
3351 width and height - both may be a percentage (followed by ‘%’).
3352 If omitted, half of the terminal size is used.
3353 -B does not surround the popup by a border.
3355 -b sets the type of characters used for drawing popup borders.
3357 When -B is specified, the -b option is ignored. See
3358 popup-border-lines for possible values for border-lines.
3359 -s sets the style for the popup and -S sets the style for the
3361 popup border (see STYLES).
3362 -e takes the form ‘VARIABLE=value’ and sets an environment vari‐
3364 able for the popup; it may be specified multiple times.
3365 -T is a format for the popup title (see FORMATS).
3367 The -C flag closes any popup on the client.
3369 show-prompt-history [-T prompt-type]
3371 (alias: showphist)
3372 Display status prompt history for prompt type prompt-type. If -T
3373 is omitted, then show history for all types. See command-prompt
3374 for possible values for prompt-type.
3375
3377 tmux maintains a set of named paste buffers. Each buffer may be either
3378 explicitly or automatically named. Explicitly named buffers are named
3379 when created with the set-buffer or load-buffer commands, or by renaming
3380 an automatically named buffer with set-buffer -n. Automatically named
3381 buffers are given a name such as ‘buffer0001’, ‘buffer0002’ and so on.
3382 When the buffer-limit option is reached, the oldest automatically named
3383 buffer is deleted. Explicitly named buffers are not subject to
3384 buffer-limit and may be deleted with the delete-buffer command.
3385 Buffers may be added using copy-mode or the set-buffer and load-buffer
3387 commands, and pasted into a window using the paste-buffer command. If a
3388 buffer command is used and no buffer is specified, the most recently
3389 added automatically named buffer is assumed.
3390 A configurable history buffer is also maintained for each window. By de‐
3392 fault, up to 2000 lines are kept; this can be altered with the
3393 history-limit option (see the set-option command above).
3394 The buffer commands are as follows:
3396 choose-buffer [-NZr] [-F format] [-f filter] [-K key-format] [-O
3398 sort-order] [-t target-pane] [template]
3399 Put a pane into buffer mode, where a buffer may be chosen inter‐
3400 actively from a list. Each buffer is shown on one line. A
3401 shortcut key is shown on the left in brackets allowing for imme‐
3402 diate choice, or the list may be navigated and an item chosen or
3403 otherwise manipulated using the keys below. -Z zooms the pane.
3404 The following keys may be used in buffer mode:
3405 Key Function
3407 Enter Paste selected buffer
3408 Up Select previous buffer
3409 Down Select next buffer
3410 C-s Search by name or content
3411 n Repeat last search
3412 t Toggle if buffer is tagged
3413 T Tag no buffers
3414 C-t Tag all buffers
3415 p Paste selected buffer
3416 P Paste tagged buffers
3417 d Delete selected buffer
3418 D Delete tagged buffers
3419 e Open the buffer in an editor
3420 f Enter a format to filter items
3421 O Change sort field
3422 r Reverse sort order
3423 v Toggle preview
3424 q Exit mode
3425 After a buffer is chosen, ‘%%’ is replaced by the buffer name in
3427 template and the result executed as a command. If template is
3428 not given, "paste-buffer -b '%%'" is used.
3429 -O specifies the initial sort field: one of ‘time’ (creation),
3431 ‘name’ or ‘size’. -r reverses the sort order. -f specifies an
3432 initial filter: the filter is a format - if it evaluates to zero,
3433 the item in the list is not shown, otherwise it is shown. If a
3434 filter would lead to an empty list, it is ignored. -F specifies
3435 the format for each item in the list and -K a format for each
3436 shortcut key; both are evaluated once for each line. -N starts
3437 without the preview. This command works only if at least one
3438 client is attached.
3439 clear-history [-H] [-t target-pane]
3441 (alias: clearhist)
3442 Remove and free the history for the specified pane. -H also re‐
3443 moves all hyperlinks.
3444 delete-buffer [-b buffer-name]
3446 (alias: deleteb)
3447 Delete the buffer named buffer-name, or the most recently added
3448 automatically named buffer if not specified.
3449 list-buffers [-F format] [-f filter]
3451 (alias: lsb)
3452 List the global buffers. -F specifies the format of each line
3453 and -f a filter. Only buffers for which the filter is true are
3454 shown. See the FORMATS section.
3455 load-buffer [-w] [-b buffer-name] [-t target-client] path
3457 (alias: loadb)
3458 Load the contents of the specified paste buffer from path. If -w
3459 is given, the buffer is also sent to the clipboard for
3460 target-client using the xterm(1) escape sequence, if possible.
3461 paste-buffer [-dpr] [-b buffer-name] [-s separator] [-t target-pane]
3463 (alias: pasteb)
3464 Insert the contents of a paste buffer into the specified pane.
3465 If not specified, paste into the current one. With -d, also
3466 delete the paste buffer. When output, any linefeed (LF) charac‐
3467 ters in the paste buffer are replaced with a separator, by de‐
3468 fault carriage return (CR). A custom separator may be specified
3469 using the -s flag. The -r flag means to do no replacement
3470 (equivalent to a separator of LF). If -p is specified, paste
3471 bracket control codes are inserted around the buffer if the ap‐
3472 plication has requested bracketed paste mode.
3473 save-buffer [-a] [-b buffer-name] path
3475 (alias: saveb)
3476 Save the contents of the specified paste buffer to path. The -a
3477 option appends to rather than overwriting the file.
3478 set-buffer [-aw] [-b buffer-name] [-t target-client] [-n new-buffer-name]
3480 data
3481 (alias: setb)
3482 Set the contents of the specified buffer to data. If -w is
3483 given, the buffer is also sent to the clipboard for target-client
3484 using the xterm(1) escape sequence, if possible. The -a option
3485 appends to rather than overwriting the buffer. The -n option re‐
3486 names the buffer to new-buffer-name.
3487 show-buffer [-b buffer-name]
3489 (alias: showb)
3490 Display the contents of the specified buffer.
3491
3493 Miscellaneous commands are as follows:
3494 clock-mode [-t target-pane]
3496 Display a large clock.
3497 if-shell [-bF] [-t target-pane] shell-command command [command]
3499 (alias: if)
3500 Execute the first command if shell-command (run with /bin/sh) re‐
3501 turns success or the second command otherwise. Before being exe‐
3502 cuted, shell-command is expanded using the rules specified in the
3503 FORMATS section, including those relevant to target-pane. With
3504 -b, shell-command is run in the background.
3505 If -F is given, shell-command is not executed but considered suc‐
3507 cess if neither empty nor zero (after formats are expanded).
3508 lock-server
3510 (alias: lock)
3511 Lock each client individually by running the command specified by
3512 the lock-command option.
3513 run-shell [-bC] [-c start-directory] [-d delay] [-t target-pane]
3515 [shell-command]
3516 (alias: run)
3517 Execute shell-command using /bin/sh or (with -C) a tmux command
3518 in the background without creating a window. Before being exe‐
3519 cuted, shell-command is expanded using the rules specified in the
3520 FORMATS section. With -b, the command is run in the background.
3521 -d waits for delay seconds before starting the command. If -c is
3522 given, the current working directory is set to start-directory.
3523 If -C is not given, any output to stdout is displayed in view
3524 mode (in the pane specified by -t or the current pane if omitted)
3525 after the command finishes. If the command fails, the exit sta‐
3526 tus is also displayed.
3527 wait-for [-L | -S | -U] channel
3529 (alias: wait)
3530 When used without options, prevents the client from exiting until
3531 woken using wait-for -S with the same channel. When -L is used,
3532 the channel is locked and any clients that try to lock the same
3533 channel are made to wait until the channel is unlocked with
3534 wait-for -U.
3535
3537 When a tmux client detaches, it prints a message. This may be one of:
3538 detached (from session ...)
3540 The client was detached normally.
3541 detached and SIGHUP
3543 The client was detached and its parent sent the SIGHUP signal
3544 (for example with detach-client -P).
3545 lost tty
3547 The client's tty(4) or pty(4) was unexpectedly destroyed.
3548 terminated
3550 The client was killed with SIGTERM.
3551 too far behind
3553 The client is in control mode and became unable to keep up with
3554 the data from tmux.
3555 exited The server exited when it had no sessions.
3557 server exited
3559 The server exited when it received SIGTERM.
3560 server exited unexpectedly
3562 The server crashed or otherwise exited without telling the client
3563 the reason.
3564
3566 tmux understands some unofficial extensions to terminfo(5). It is not
3567 normally necessary to set these manually, instead the terminal-features
3568 option should be used.
3569 AX An existing extension that tells tmux the terminal supports de‐
3571 fault colours.
3572 Bidi Tell tmux that the terminal supports the VTE bidirectional text
3574 extensions.
3575 Cs, Cr Set the cursor colour. The first takes a single string argument
3577 and is used to set the colour; the second takes no arguments and
3578 restores the default cursor colour. If set, a sequence such as
3579 this may be used to change the cursor colour from inside tmux:
3580 $ printf '\033]12;red\033\\'
3582 The colour is an X(7) colour, see XParseColor(3).
3584 Cmg, Clmg, Dsmg, Enmg
3586 Set, clear, disable or enable DECSLRM margins. These are set au‐
3587 tomatically if the terminal reports it is VT420 compatible.
3588 Dsbp, Enbp
3590 Disable and enable bracketed paste. These are set automatically
3591 if the XT capability is present.
3592 Dseks, Eneks
3594 Disable and enable extended keys.
3595 Dsfcs, Enfcs
3597 Disable and enable focus reporting. These are set automatically
3598 if the XT capability is present.
3599 Hls Set or clear a hyperlink annotation.
3601 Nobr Tell tmux that the terminal does not use bright colors for bold
3603 display.
3604 Rect Tell tmux that the terminal supports rectangle operations.
3606 Smol Enable the overline attribute.
3608 Smulx Set a styled underscore. The single parameter is one of: 0 for
3610 no underscore, 1 for normal underscore, 2 for double underscore,
3611 3 for curly underscore, 4 for dotted underscore and 5 for dashed
3612 underscore.
3613 Setulc, Setulc1, ol
3615 Set the underscore colour or reset to the default. Setulc is for
3616 RGB colours and Setulc1 for ANSI or 256 colours. The Setulc ar‐
3617 gument is (red * 65536) + (green * 256) + blue where each is be‐
3618 tween 0 and 255.
3619 Ss, Se Set or reset the cursor style. If set, a sequence such as this
3621 may be used to change the cursor to an underline:
3622 $ printf '\033[4 q'
3624 If Se is not set, Ss with argument 0 will be used to reset the
3626 cursor style instead.
3627 Swd Set the opening sequence for the working directory notification.
3629 The sequence is terminated using the standard fsl capability.
3630 Sxl Indicates that the terminal supports SIXEL.
3632 Sync Start (parameter is 1) or end (parameter is 2) a synchronized up‐
3634 date.
3635 Tc Indicate that the terminal supports the ‘direct colour’ RGB es‐
3637 cape sequence (for example, \e[38;2;255;255;255m).
3638 If supported, this is used for the initialize colour escape se‐
3640 quence (which may be enabled by adding the ‘initc’ and ‘ccc’ ca‐
3641 pabilities to the tmux [22mterminfo(5) entry).
3642 This is equivalent to the RGB terminfo(5) capability.
3644 Ms Store the current buffer in the host terminal's selection (clip‐
3646 board). See the set-clipboard option above and the xterm(1) man
3647 page.
3648 XT This is an existing extension capability that tmux uses to mean
3650 that the terminal supports the xterm(1) title set sequences and
3651 to automatically set some of the capabilities above.
3652
3654 tmux offers a textual interface called control mode. This allows appli‐
3655 cations to communicate with tmux using a simple text-only protocol.
3656 In control mode, a client sends tmux commands or command sequences termi‐
3658 nated by newlines on standard input. Each command will produce one block
3659 of output on standard output. An output block consists of a %begin line
3660 followed by the output (which may be empty). The output block ends with
3661 a %end or %error. %begin and matching %end or %error have three argu‐
3662 ments: an integer time (as seconds from epoch), command number and flags
3663 (currently not used). For example:
3664 %begin 1363006971 2 1
3666 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
3667 %end 1363006971 2 1
3668 The refresh-client -C command may be used to set the size of a client in
3670 control mode.
3671 In control mode, tmux outputs notifications. A notification will never
3673 occur inside an output block.
3674 The following notifications are defined:
3676 %client-detached client
3678 The client has detached.
3679 %client-session-changed client session-id name
3681 The client is now attached to the session with ID session-id,
3682 which is named name.
3683 %config-error error
3685 An error has happened in a configuration file.
3686 %continue pane-id
3688 The pane has been continued after being paused (if the
3689 pause-after flag is set, see refresh-client -A).
3690 %exit [reason]
3692 The tmux client is exiting immediately, either because it is not
3693 attached to any session or an error occurred. If present, reason
3694 describes why the client exited.
3695 %extended-output pane-id age ... : value
3697 New form of %output sent when the pause-after flag is set. age
3698 is the time in milliseconds for which tmux had buffered the out‐
3699 put before it was sent. Any subsequent arguments up until a sin‐
3700 gle ‘:’ are for future use and should be ignored.
3701 %layout-change window-id window-layout window-visible-layout window-flags
3703 The layout of a window with ID window-id changed. The new layout
3704 is window-layout. The window's visible layout is
3705 window-visible-layout and the window flags are window-flags.
3706 %message message
3708 A message sent with the display-message command.
3709 %output pane-id value
3711 A window pane produced output. value escapes non-printable char‐
3712 acters and backslash as octal \xxx.
3713 %pane-mode-changed pane-id
3715 The pane with ID pane-id has changed mode.
3716 %paste-buffer-changed name
3718 Paste buffer name has been changed.
3719 %paste-buffer-deleted name
3721 Paste buffer name has been deleted.
3722 %pause pane-id
3724 The pane has been paused (if the pause-after flag is set).
3725 %session-changed session-id name
3727 The client is now attached to the session with ID session-id,
3728 which is named name.
3729 %session-renamed name
3731 The current session was renamed to name.
3732 %session-window-changed session-id window-id
3734 The session with ID session-id changed its active window to the
3735 window with ID window-id.
3736 %sessions-changed
3738 A session was created or destroyed.
3739 %subscription-changed name session-id window-id window-index pane-id ...
3741 : value
3742 The value of the format associated with subscription name has
3743 changed to value. See refresh-client -B. Any arguments after
3744 pane-id up until a single ‘:’ are for future use and should be
3745 ignored.
3746 %unlinked-window-add window-id
3748 The window with ID window-id was created but is not linked to the
3749 current session.
3750 %unlinked-window-close window-id
3752 The window with ID window-id, which is not linked to the current
3753 session, was closed.
3754 %unlinked-window-renamed window-id
3756 The window with ID window-id, which is not linked to the current
3757 session, was renamed.
3758 %window-add window-id
3760 The window with ID window-id was linked to the current session.
3761 %window-close window-id
3763 The window with ID window-id closed.
3764 %window-pane-changed window-id pane-id
3766 The active pane in the window with ID window-id changed to the
3767 pane with ID pane-id.
3768 %window-renamed window-id name
3770 The window with ID window-id was renamed to name.
3771
3773 When tmux is started, it inspects the following environment variables:
3774 EDITOR If the command specified in this variable contains the string
3776 ‘vi’ and VISUAL is unset, use vi-style key bindings. Overrid‐
3777 den by the mode-keys and status-keys options.
3778 HOME The user's login directory. If unset, the passwd(5) database
3780 is consulted.
3781 LC_CTYPE The character encoding locale(1). It is used for two separate
3783 purposes. For output to the terminal, UTF-8 is used if the -u
3784 option is given or if LC_CTYPE contains "UTF-8" or "UTF8".
3785 Otherwise, only ASCII characters are written and non-ASCII
3786 characters are replaced with underscores (‘_’). For input,
3787 tmux always runs with a UTF-8 locale. If en_US.UTF-8 is pro‐
3788 vided by the operating system, it is used and LC_CTYPE is ig‐
3789 nored for input. Otherwise, LC_CTYPE tells tmux what the UTF-8
3790 locale is called on the current system. If the locale speci‐
3791 fied by LC_CTYPE is not available or is not a UTF-8 locale,
3792 tmux exits with an error message.
3793 LC_TIME The date and time format locale(1). It is used for locale-de‐
3795 pendent strftime(3) format specifiers.
3796 PWD The current working directory to be set in the global environ‐
3798 ment. This may be useful if it contains symbolic links. If
3799 the value of the variable does not match the current working
3800 directory, the variable is ignored and the result of getcwd(3)
3801 is used instead.
3802 SHELL The absolute path to the default shell for new windows. See
3804 the default-shell option for details.
3805 TMUX_TMPDIR
3807 The parent directory of the directory containing the server
3808 sockets. See the -L option for details.
3809 VISUAL If the command specified in this variable contains the string
3811 ‘vi’, use vi-style key bindings. Overridden by the mode-keys
3812 and status-keys options.
3813
3815 ~/.tmux.conf
3816 $XDG_CONFIG_HOME/tmux/tmux.conf
3817 ~/.config/tmux/tmux.conf
3818 Default tmux configuration file.
3819 /etc/tmux.conf System-wide configuration file.
3820
3822 To create a new tmux session running vi(1):
3823 $ tmux new-session vi
3825 Most commands have a shorter form, known as an alias. For new-session,
3827 this is new:
3828 $ tmux new vi
3830 Alternatively, the shortest unambiguous form of a command is accepted.
3832 If there are several options, they are listed:
3833 $ tmux n
3835 ambiguous command: n, could be: new-session, new-window, next-window
3836 Within an active session, a new window may be created by typing ‘C-b c’
3838 (Ctrl followed by the ‘b’ key followed by the ‘c’ key).
3839 Windows may be navigated with: ‘C-b 0’ (to select window 0), ‘C-b 1’ (to
3841 select window 1), and so on; ‘C-b n’ to select the next window; and ‘C-b
3842 p’ to select the previous window.
3843 A session may be detached using ‘C-b d’ (or by an external event such as
3845 ssh(1) disconnection) and reattached with:
3846 $ tmux attach-session
3848 Typing ‘C-b ?’ lists the current key bindings in the current window; up
3850 and down may be used to navigate the list or ‘q’ to exit from it.
3851 Commands to be run when the tmux server is started may be placed in the
3853 ~/.tmux.conf configuration file. Common examples include:
3854 Changing the default prefix key:
3856 set-option -g prefix C-a
3858 unbind-key C-b
3859 bind-key C-a send-prefix
3860 Turning the status line off, or changing its colour:
3862 set-option -g status off
3864 set-option -g status-style bg=blue
3865 Setting other options, such as the default command, or locking after 30
3867 minutes of inactivity:
3868 set-option -g default-command "exec /bin/ksh"
3870 set-option -g lock-after-time 1800
3871 Creating new key bindings:
3873 bind-key b set-option status
3875 bind-key / command-prompt "split-window 'exec man %%'"
3876 bind-key S command-prompt "new-window -n %1 'ssh %1'"
3877
3879 pty(4)
3880
3882 Nicholas Marriott <nicholas.marriott@gmail.com>
3883BSD December 20, 2023 BSD