1TMUX(1) BSD General Commands Manual TMUX(1)
2
4 tmux — terminal multiplexer
5
7 tmux [-2CluvV] [-c shell-command] [-f file] [-L socket-name]
8 [-S socket-path] [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
13 detached 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 -C Start in control mode (see the CONTROL MODE section).
44 Given twice (-CC) disables echo.
45 -c shell-command
47 Execute shell-command using the default shell. If neces‐
48 sary, the tmux server will be started to retrieve the
49 default-shell option. This option is for compatibility
50 with sh(1) when tmux is used as a login shell.
51 -f file Specify an alternative configuration file. By default,
53 tmux loads the system configuration file from
54 /etc/tmux.conf, if present, then looks for a user configu‐
55 ration file at ~/.tmux.conf.
56 The configuration file is a set of tmux commands which are
58 executed in sequence when the server is first started.
59 tmux loads configuration files once when the server process
60 has started. The source-file command may be used to load a
61 file later.
62 tmux shows any error messages from commands in configura‐
64 tion files in the first session created, and continues to
65 process the rest of the configuration file.
66 -L socket-name
68 tmux stores the server socket in a directory under
69 TMUX_TMPDIR or /tmp if it is unset. The default socket is
70 named default. This option allows a different socket name
71 to be specified, allowing several independent tmux servers
72 to be run. Unlike -S a full path is not necessary: the
73 sockets are all created in the same directory.
74 If the socket is accidentally removed, the SIGUSR1 signal
76 may be sent to the tmux server process to recreate it (note
77 that this will fail if any parent directories are missing).
78 -l Behave as a login shell. This flag currently has no effect
80 and is for compatibility with other shells when using tmux
81 as a login shell.
82 -S socket-path
84 Specify a full alternative path to the server socket. If
85 -S is specified, the default socket directory is not used
86 and any -L flag is ignored.
87 -u Write UTF-8 output to the terminal even if the first envi‐
89 ronment variable of LC_ALL, LC_CTYPE, or LANG that is set
90 does not contain "UTF-8" or "UTF8".
91 -v Request verbose logging. Log messages will be saved into
93 tmux-client-PID.log and tmux-server-PID.log files in the
94 current directory, where PID is the PID of the server or
95 client process. If -v is specified twice, an additional
96 tmux-out-PID.log file is generated with a copy of every‐
97 thing tmux writes to the terminal.
98 The SIGUSR2 signal may be sent to the tmux server process
100 to toggle logging between on (as if -v was given) and off.
101 -V Report the tmux version.
103 command [flags]
105 This specifies one of a set of commands used to control
106 tmux, as described in the following sections. If no com‐
107 mands are specified, the new-session command is assumed.
108
110 tmux may be controlled from an attached client by using a key combination
111 of a prefix key, ‘C-b’ (Ctrl-b) by default, followed by a command key.
112 The default command key bindings are:
114 C-b Send the prefix key (C-b) through to the application.
116 C-o Rotate the panes in the current window forwards.
117 C-z Suspend the tmux client.
118 ! Break the current pane out of the window.
119 " Split the current pane into two, top and bottom.
120 # List all paste buffers.
121 $ Rename the current session.
122 % Split the current pane into two, left and right.
123 & Kill the current window.
124 ' Prompt for a window index to select.
125 ( Switch the attached client to the previous session.
126 ) Switch the attached client to the next session.
127 , Rename the current window.
128 - Delete the most recently copied buffer of text.
129 . Prompt for an index to move the current window.
130 0 to 9 Select windows 0 to 9.
131 : Enter the tmux command prompt.
132 ; Move to the previously active pane.
133 = Choose which buffer to paste interactively from a list.
134 ? List all key bindings.
135 D Choose a client to detach.
136 L Switch the attached client back to the last session.
137 [ Enter copy mode to copy text or view the history.
138 ] Paste the most recently copied buffer of text.
139 c Create a new window.
140 d Detach the current client.
141 f Prompt to search for text in open windows.
142 i Display some information about the current window.
143 l Move to the previously selected window.
144 m Mark the current pane (see select-pane -m).
145 M Clear the marked pane.
146 n Change to the next window.
147 o Select the next pane in the current window.
148 p Change to the previous window.
149 q Briefly display pane indexes.
150 r Force redraw of the attached client.
151 s Select a new session for the attached client interac‐
152 tively.
153 t Show the time.
154 w Choose the current window interactively.
155 x Kill the current pane.
156 z Toggle zoom state of the current pane.
157 { Swap the current pane with the previous pane.
158 } Swap the current pane with the next pane.
159 ~ Show previous messages from tmux, if any.
160 Page Up Enter copy mode and scroll one page up.
161 Up, Down
162 Left, Right
163 Change to the pane above, below, to the left, or to the
164 right of the current pane.
165 M-1 to M-5 Arrange panes in one of the five preset layouts: even-
166 horizontal, even-vertical, main-horizontal, main-verti‐
167 cal, or tiled.
168 Space Arrange the current window in the next preset layout.
169 M-n Move to the next window with a bell or activity marker.
170 M-o Rotate the panes in the current window backwards.
171 M-p Move to the previous window with a bell or activity
172 marker.
173 C-Up, C-Down
174 C-Left, C-Right
175 Resize the current pane in steps of one cell.
176 M-Up, M-Down
177 M-Left, M-Right
178 Resize the current pane in steps of five cells.
179 Key bindings may be changed with the bind-key and unbind-key commands.
181
183 tmux supports a large number of commands which can be used to control its
184 behaviour. Each command is named and can accept zero or more flags and
185 arguments. They may be bound to a key with the bind-key command or run
186 from the shell prompt, a shell script, a configuration file or the com‐
187 mand prompt. For example, the same set-option command run from the shell
188 prompt, from ~/.tmux.conf and bound to a key may look like:
189 $ tmux set-option -g status-style bg=cyan
191 set-option -g status-style bg=cyan
193 bind-key C set-option -g status-style bg=cyan
195 Here, the command name is ‘set-option’, ‘-g’ is a flag and ‘status-style’
197 and ‘bg=cyan’ are arguments.
198 tmux distinguishes between command parsing and execution. In order to
200 execute a command, tmux needs it to be split up into its name and argu‐
201 ments. This is command parsing. If a command is run from the shell, the
202 shell parses it; from inside tmux or from a configuration file, tmux
203 does. Examples of when tmux parses commands are:
204 - in a configuration file;
206 - typed at the command prompt (see command-prompt);
208 - given to bind-key;
210 - passed as arguments to if-shell or confirm-before.
212 To execute commands, each client has a ‘command queue’. A global command
214 queue not attached to any client is used on startup for configuration
215 files like ~/.tmux.conf. Parsed commands added to the queue are executed
216 in order. Some commands, like if-shell and confirm-before, parse their
217 argument to create a new command which is inserted immediately after
218 themselves. This means that arguments can be parsed twice or more - once
219 when the parent command (such as if-shell) is parsed and again when it
220 parses and executes its command. Commands like if-shell, run-shell and
221 display-panes stop execution of subsequent commands on the queue until
222 something happens - if-shell and run-shell until a shell command finishes
223 and display-panes until a key is pressed. For example, the following
224 commands:
225 new-session; new-window
227 if-shell "true" "split-window"
228 kill-session
229 Will execute new-session, new-window, if-shell, the shell command
231 true(1), split-window and kill-session in that order.
232 The COMMANDS section lists the tmux commands and their arguments.
234
236 This section describes the syntax of commands parsed by tmux, for example
237 in a configuration file or at the command prompt. Note that when com‐
238 mands are entered into the shell, they are parsed by the shell - see for
239 example ksh(1) or csh(1).
240 Each command is terminated by a newline or a semicolon (;). Commands
242 separated by semicolons together form a ‘command sequence’ - if a command
243 in the sequence encounters an error, no subsequent commands are executed.
244 Comments are marked by the unquoted # character - any remaining text
246 after a comment is ignored until the end of the line.
247 If the last character of a line is \, the line is joined with the follow‐
249 ing line (the \ and the newline are completely removed). This is called
250 line continuation and applies both inside and outside quoted strings and
251 in comments, but not inside braces.
252 Command arguments may be specified as strings surrounded by single (')
254 quotes, double quotes (") or braces ({}). This is required when the
255 argument contains any special character. Single and double quoted
256 strings cannot span multiple lines except with line continuation. Braces
257 can span multiple lines.
258 Outside of quotes and inside double quotes, these replacements are per‐
260 formed:
261 - Environment variables preceded by $ are replaced with their
263 value from the global environment (see the GLOBAL AND SESSION
264 ENVIRONMENT section).
265 - A leading ~ or ~user is expanded to the home directory of the
267 current or specified user.
268 - \uXXXX or \uXXXXXXXX is replaced by the Unicode codepoint cor‐
270 responding to the given four or eight digit hexadecimal number.
271 - When preceded (escaped) by a \, the following characters are
273 replaced: \e by the escape character; \r by a carriage return;
274 \n by a newline; and \t by a tab.
275 - \ooo is replaced by a character of the octal value ooo. Three
277 octal digits are required, for example \001. The largest valid
278 character is \377.
279 - Any other characters preceded by \ are replaced by themselves
281 (that is, the \ is removed) and are not treated as having any
282 special meaning - so for example \; will not mark a command
283 sequence and \$ will not expand an environment variable.
284 Braces are similar to single quotes in that the text inside is taken lit‐
286 erally without any replacements but this also includes line continuation.
287 Braces can span multiple lines in which case a literal newline is
288 included in the string. They are designed to avoid the need for addi‐
289 tional escaping when passing a group of tmux or shell commands as an
290 argument (for example to if-shell or pipe-pane). These two examples pro‐
291 duce an identical command - note that no escaping is needed when using
292 {}:
293 if-shell true {
295 display -p 'brace-dollar-foo: }$foo'
296 }
297 if-shell true "\n display -p 'brace-dollar-foo: }\$foo'\n"
299 Braces may be enclosed inside braces, for example:
301 bind x if-shell "true" {
303 if-shell "true" {
304 display "true!"
305 }
306 }
307 Environment variables may be set by using the syntax ‘name=value’, for
309 example ‘HOME=/home/user’. Variables set during parsing are added to the
310 global environment.
311 Commands may be parsed conditionally by surrounding them with ‘%if’,
313 ‘%elif’, ‘%else’ and ‘%endif’. The argument to ‘%if’ and ‘%elif’ is
314 expanded as a format (see FORMATS) and if it evaluates to false (zero or
315 empty), subsequent text is ignored until the closing ‘%elif’, ‘%else’ or
316 ‘%endif’. For example:
317 %if "#{==:#{host},myhost}"
319 set -g status-style bg=red
320 %elif "#{==:#{host},myotherhost}"
321 set -g status-style bg=green
322 %else
323 set -g status-style bg=blue
324 %endif
325 Will change the status line to red if running on ‘myhost’, green if run‐
327 ning on ‘myotherhost’, or blue if running on another host. Conditionals
328 may be given on one line, for example:
329 %if #{==:#{host},myhost} set -g status-style bg=red %endif
331
333 This section describes the commands supported by tmux. Most commands
334 accept the optional -t (and sometimes -s) argument with one of
335 target-client, target-session, target-window, or target-pane. These
336 specify the client, session, window or pane which a command should
337 affect.
338 target-client should be the name of the client, typically the pty(4) file
340 to which the client is connected, for example either of /dev/ttyp1 or
341 ttyp1 for the client attached to /dev/ttyp1. If no client is specified,
342 tmux attempts to work out the client currently in use; if that fails, an
343 error is reported. Clients may be listed with the list-clients command.
344 target-session is tried as, in order:
346 1. A session ID prefixed with a $.
348 2. An exact name of a session (as listed by the list-sessions
350 command).
351 3. The start of a session name, for example ‘mysess’ would match
353 a session named ‘mysession’.
354 4. An fnmatch(3) pattern which is matched against the session
356 name.
357 If the session name is prefixed with an ‘=’, only an exact match is
359 accepted (so ‘=mysess’ will only match exactly ‘mysess’, not
360 ‘mysession’).
361 If a single session is found, it is used as the target session; multiple
363 matches produce an error. If a session is omitted, the current session
364 is used if available; if no current session is available, the most
365 recently used is chosen.
366 target-window (or src-window or dst-window) specifies a window in the
368 form session:window. session follows the same rules as for
369 target-session, and window is looked for in order as:
370 1. A special token, listed below.
372 2. A window index, for example ‘mysession:1’ is window 1 in ses‐
374 sion ‘mysession’.
375 3. A window ID, such as @1.
377 4. An exact window name, such as ‘mysession:mywindow’.
379 5. The start of a window name, such as ‘mysession:mywin’.
381 6. As an fnmatch(3) pattern matched against the window name.
383 Like sessions, a ‘=’ prefix will do an exact match only. An empty window
385 name specifies the next unused index if appropriate (for example the
386 new-window and link-window commands) otherwise the current window in
387 session is chosen.
388 The following special tokens are available to indicate particular win‐
390 dows. Each has a single-character alternative form.
391 Token Meaning
393 {start} ^ The lowest-numbered window
394 {end} $ The highest-numbered window
395 {last} ! The last (previously current) window
396 {next} + The next window by number
397 {previous} - The previous window by number
398 target-pane (or src-pane or dst-pane) may be a pane ID or takes a similar
400 form to target-window but with the optional addition of a period followed
401 by a pane index or pane ID, for example: ‘mysession:mywindow.1’. If the
402 pane index is omitted, the currently active pane in the specified window
403 is used. The following special tokens are available for the pane index:
404 Token Meaning
406 {last} ! The last (previously active) pane
407 {next} + The next pane by number
408 {previous} - The previous pane by number
409 {top} The top pane
410 {bottom} The bottom pane
411 {left} The leftmost pane
412 {right} The rightmost pane
413 {top-left} The top-left pane
414 {top-right} The top-right pane
415 {bottom-left} The bottom-left pane
416 {bottom-right} The bottom-right pane
417 {up-of} The pane above the active pane
418 {down-of} The pane below the active pane
419 {left-of} The pane to the left of the active pane
420 {right-of} The pane to the right of the active pane
421 The tokens ‘+’ and ‘-’ may be followed by an offset, for example:
423 select-window -t:+2
425 In addition, target-session, target-window or target-pane may consist
427 entirely of the token ‘{mouse}’ (alternative form ‘=’) to specify the
428 session, window or pane where the most recent mouse event occurred (see
429 the MOUSE SUPPORT section) or ‘{marked}’ (alternative form ‘~’) to spec‐
430 ify the marked pane (see select-pane -m).
431 Sessions, window and panes are each numbered with a unique ID; session
433 IDs are prefixed with a ‘$’, windows with a ‘@’, and panes with a ‘%’.
434 These are unique and are unchanged for the life of the session, window or
435 pane in the tmux server. The pane ID is passed to the child process of
436 the pane in the TMUX_PANE environment variable. IDs may be displayed
437 using the ‘session_id’, ‘window_id’, or ‘pane_id’ formats (see the
438 FORMATS section) and the display-message, list-sessions, list-windows or
439 list-panes commands.
440 shell-command arguments are sh(1) commands. This may be a single argu‐
442 ment passed to the shell, for example:
443 new-window 'vi /etc/passwd'
445 Will run:
447 /bin/sh -c 'vi /etc/passwd'
449 Additionally, the new-window, new-session, split-window, respawn-window
451 and respawn-pane commands allow shell-command to be given as multiple
452 arguments and executed directly (without ‘sh -c’). This can avoid issues
453 with shell quoting. For example:
454 $ tmux new-window vi /etc/passwd
456 Will run vi(1) directly without invoking the shell.
458 command [arguments] refers to a tmux command, either passed with the com‐
460 mand and arguments separately, for example:
461 bind-key F1 set-option status off
463 Or passed as a single string argument in .tmux.conf, for example:
465 bind-key F1 { set-option status off }
467 Example tmux commands include:
469 refresh-client -t/dev/ttyp2
471 rename-session -tfirst newname
473 set-option -wt:0 monitor-activity on
475 new-window ; split-window -d
477 bind-key R source-file ~/.tmux.conf \; \
479 display-message "source-file done"
480 Or from sh(1):
482 $ tmux kill-window -t :1
484 $ tmux new-window \; split-window -d
486 $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach
488
490 The tmux server manages clients, sessions, windows and panes. Clients
491 are attached to sessions to interact with them, either when they are cre‐
492 ated with the new-session command, or later with the attach-session com‐
493 mand. Each session has one or more windows linked into it. Windows may
494 be linked to multiple sessions and are made up of one or more panes, each
495 of which contains a pseudo terminal. Commands for creating, linking and
496 otherwise manipulating windows are covered in the WINDOWS AND PANES sec‐
497 tion.
498 The following commands are available to manage clients and sessions:
500 attach-session [-dErx] [-c working-directory] [-t target-session]
502 (alias: attach)
503 If run from outside tmux, create a new client in the current ter‐
504 minal and attach it to target-session. If used from inside,
505 switch the current client. If -d is specified, any other clients
506 attached to the session are detached. If -x is given, send
507 SIGHUP to the parent process of the client as well as detaching
508 the client, typically causing it to exit. -r signifies the
509 client is read-only (only keys bound to the detach-client or
510 switch-client commands have any effect)
511 If no server is started, attach-session will attempt to start it;
513 this will fail unless sessions are created in the configuration
514 file.
515 The target-session rules for attach-session are slightly
517 adjusted: if tmux needs to select the most recently used session,
518 it will prefer the most recently used unattached session.
519 -c will set the session working directory (used for new windows)
521 to working-directory.
522 If -E is used, the update-environment option will not be applied.
524 detach-client [-aP] [-E shell-command] [-s target-session] [-t
526 target-client]
527 (alias: detach)
528 Detach the current client if bound to a key, the client specified
529 with -t, or all clients currently attached to the session speci‐
530 fied by -s. The -a option kills all but the client given with
531 -t. If -P is given, send SIGHUP to the parent process of the
532 client, typically causing it to exit. With -E, run shell-command
533 to replace the client.
534 has-session [-t target-session]
536 (alias: has)
537 Report an error and exit with 1 if the specified session does not
538 exist. If it does exist, exit with 0.
539 kill-server
541 Kill the tmux server and clients and destroy all sessions.
542 kill-session [-aC] [-t target-session]
544 Destroy the given session, closing any windows linked to it and
545 no other sessions, and detaching all clients attached to it. If
546 -a is given, all sessions but the specified one is killed. The
547 -C flag clears alerts (bell, activity, or silence) in all windows
548 linked to the session.
549 list-clients [-F format] [-t target-session]
551 (alias: lsc)
552 List all clients attached to the server. For the meaning of the
553 -F flag, see the FORMATS section. If target-session is speci‐
554 fied, list only clients connected to that session.
555 list-commands [-F format] [command]
557 (alias: lscm)
558 List the syntax of command or - if omitted - of all commands sup‐
559 ported by tmux.
560 list-sessions [-F format]
562 (alias: ls)
563 List all sessions managed by the server. For the meaning of the
564 -F flag, see the FORMATS section.
565 lock-client [-t target-client]
567 (alias: lockc)
568 Lock target-client, see the lock-server command.
569 lock-session [-t target-session]
571 (alias: locks)
572 Lock all clients attached to target-session.
573 new-session [-AdDEPX] [-c start-directory] [-F format] [-n window-name]
575 [-s session-name] [-t group-name] [-x width] [-y height]
576 [shell-command]
577 (alias: new)
578 Create a new session with name session-name.
579 The new session is attached to the current terminal unless -d is
581 given. window-name and shell-command are the name of and shell
582 command to execute in the initial window. With -d, the initial
583 size comes from the global default-size option; -x and -y can be
584 used to specify a different size. ‘-’ uses the size of the cur‐
585 rent client if any. If -x or -y is given, the default-size
586 option is set for the session.
587 If run from a terminal, any termios(4) special characters are
589 saved and used for new windows in the new session.
590 The -A flag makes new-session behave like attach-session if
592 session-name already exists; in this case, -D behaves like -d to
593 attach-session, and -X behaves like -x to attach-session.
594 If -t is given, it specifies a session group. Sessions in the
596 same group share the same set of windows - new windows are linked
597 to all sessions in the group and any windows closed removed from
598 all sessions. The current and previous window and any session
599 options remain independent and any session in a group may be
600 killed without affecting the others. The group-name argument may
601 be:
602 1. the name of an existing group, in which case the new ses‐
604 sion is added to that group;
605 2. the name of an existing session - the new session is
607 added to the same group as that session, creating a new
608 group if necessary;
609 3. the name for a new group containing only the new session.
611 -n and shell-command are invalid if -t is used.
613 The -P option prints information about the new session after it
615 has been created. By default, it uses the format
616 ‘#{session_name}:’ but a different format may be specified with
617 -F.
618 If -E is used, the update-environment option will not be applied.
620 refresh-client [-cDlLRSU] [-C XxY] [-F flags] [-t target-client]
622 [adjustment]
623 (alias: refresh)
624 Refresh the current client if bound to a key, or a single client
625 if one is given with -t. If -S is specified, only update the
626 client's status line.
627 The -U, -D, -L -R, and -c flags allow the visible portion of a
629 window which is larger than the client to be changed. -U moves
630 the visible part up by adjustment rows and -D down, -L left by
631 adjustment columns and -R right. -c returns to tracking the cur‐
632 sor automatically. If adjustment is omitted, 1 is used. Note
633 that the visible position is a property of the client not of the
634 window, changing the current window in the attached session will
635 reset it.
636 -C sets the width and height of a control client and -F sets a
638 comma-separated list of flags. Currently the only flag available
639 is ‘no-output’ to disable receiving pane output.
640 -l requests the clipboard from the client using the xterm(1)
642 escape sequence and stores it in a new paste buffer.
643 -L, -R, -U and -D move the visible portion of the window left,
645 right, up or down by adjustment, if the window is larger than the
646 client. -c resets so that the position follows the cursor. See
647 the window-size option.
648 rename-session [-t target-session] new-name
650 (alias: rename)
651 Rename the session to new-name.
652 show-messages [-JT] [-t target-client]
654 (alias: showmsgs)
655 Show client messages or server information. Any messages dis‐
656 played on the status line are saved in a per-client message log,
657 up to a maximum of the limit set by the message-limit server
658 option. With -t, display the log for target-client. -J and -T
659 show debugging information about jobs and terminals.
660 source-file [-nqv] path ...
662 (alias: source)
663 Execute commands from one or more files specified by path (which
664 may be glob(7) patterns). If -q is given, no error will be
665 returned if path does not exist. With -n, the file is parsed but
666 no commands are executed. -v shows the parsed commands and line
667 numbers if possible.
668 start-server
670 (alias: start)
671 Start the tmux server, if not already running, without creating
672 any sessions.
673 Note that as by default the tmux server will exit with no ses‐
675 sions, this is only useful if a session is created in
676 ~/.tmux.conf, exit-empty is turned off, or another command is run
677 as part of the same command sequence. For example:
678 $ tmux start \; show -g
680 suspend-client [-t target-client]
682 (alias: suspendc)
683 Suspend a client by sending SIGTSTP (tty stop).
684 switch-client [-ElnprZ] [-c target-client] [-t target-session] [-T
686 key-table]
687 (alias: switchc)
688 Switch the current session for client target-client to
689 target-session. As a special case, -t may refer to a pane (a
690 target that contains ‘:’, ‘.’ or ‘%’), to change session, window
691 and pane. In that case, -Z keeps the window zoomed if it was
692 zoomed. If -l, -n or -p is used, the client is moved to the
693 last, next or previous session respectively. -r toggles whether
694 a client is read-only (see the attach-session command).
695 If -E is used, update-environment option will not be applied.
697 -T sets the client's key table; the next key from the client will
699 be interpreted from key-table. This may be used to configure
700 multiple prefix keys, or to bind commands to sequences of keys.
701 For example, to make typing ‘abc’ run the list-keys command:
702 bind-key -Ttable2 c list-keys
704 bind-key -Ttable1 b switch-client -Ttable2
705 bind-key -Troot a switch-client -Ttable1
706
708 Each window displayed by tmux may be split into one or more panes; each
709 pane takes up a certain area of the display and is a separate terminal.
710 A window may be split into panes using the split-window command. Windows
711 may be split horizontally (with the -h flag) or vertically. Panes may be
712 resized with the resize-pane command (bound to ‘C-Up’, ‘C-Down’ ‘C-Left’
713 and ‘C-Right’ by default), the current pane may be changed with the
714 select-pane command and the rotate-window and swap-pane commands may be
715 used to swap panes without changing their position. Panes are numbered
716 beginning from zero in the order they are created.
717 By default, a tmux pane permits direct access to the terminal contained
719 in the pane. A pane may also be put into one of several modes:
720 - Copy mode, which permits a section of a window or its history
722 to be copied to a paste buffer for later insertion into another
723 window. This mode is entered with the copy-mode command, bound
724 to ‘[’ by default.
725 - View mode, which is like copy mode but is entered when a com‐
727 mand that produces output, such as list-keys, is executed from
728 a key binding.
729 - Choose mode, which allows an item to be chosen from a list.
731 This may be a client, a session or window or pane, or a buffer.
732 This mode is entered with the choose-buffer, choose-client and
733 choose-tree commands.
734 In copy mode an indicator is displayed in the top-right corner of the
736 pane with the current position and the number of lines in the history.
737 Commands are sent to copy mode using the -X flag to the send-keys com‐
739 mand. When a key is pressed, copy mode automatically uses one of two key
740 tables, depending on the mode-keys option: copy-mode for emacs, or
741 copy-mode-vi for vi. Key tables may be viewed with the list-keys com‐
742 mand.
743 The following commands are supported in copy mode:
745 Command vi emacs
747 append-selection
748 append-selection-and-cancel A
749 back-to-indentation ^ M-m
750 begin-selection Space C-Space
751 bottom-line L
752 cancel q Escape
753 clear-selection Escape C-g
754 copy-end-of-line [<prefix>] D C-k
755 copy-line [<prefix>]
756 copy-pipe <command> [<prefix>]
757 copy-pipe-no-clear <command> [<prefix>]
758 copy-pipe-and-cancel <command> [<prefix>]
759 copy-selection [<prefix>]
760 copy-selection-no-clear [<prefix>]
761 copy-selection-and-cancel [<prefix>] Enter M-w
762 cursor-down j Down
763 cursor-down-and-cancel
764 cursor-left h Left
765 cursor-right l Right
766 cursor-up k Up
767 end-of-line $ C-e
768 goto-line <line> : g
769 halfpage-down C-d M-Down
770 halfpage-down-and-cancel
771 halfpage-up C-u M-Up
772 history-bottom G M->
773 history-top g M-<
774 jump-again ; ;
775 jump-backward <to> F F
776 jump-forward <to> f f
777 jump-reverse , ,
778 jump-to-backward <to> T
779 jump-to-forward <to> t
780 middle-line M M-r
781 next-matching-bracket % M-C-f
782 next-paragraph } M-}
783 next-space W
784 next-space-end E
785 next-word w
786 next-word-end e M-f
787 other-end o
788 page-down C-f PageDown
789 page-down-and-cancel
790 page-up C-b PageUp
791 previous-matching-bracket M-C-b
792 previous-paragraph { M-{
793 previous-space B
794 previous-word b M-b
795 rectangle-toggle v R
796 scroll-down C-e C-Down
797 scroll-down-and-cancel
798 scroll-up C-y C-Up
799 search-again n n
800 search-backward <for> ?
801 search-backward-incremental <for> C-r
802 search-backward-text <for>
803 search-forward <for> /
804 search-forward-incremental <for> C-s
805 search-forward-text <for>
806 search-reverse N N
807 select-line V
808 select-word
809 start-of-line 0 C-a
810 stop-selection
811 top-line H M-R
812 The search commands come in several varieties: ‘search-forward’ and
814 ‘search-backward’ search for a regular expression; the ‘-text’ variants
815 search for a plain text string rather than a regular expression;
816 ‘-incremental’ perform an incremental search and expect to be used with
817 the -i flag to the command-prompt command. ‘search-again’ repeats the
818 last search and ‘search-reverse’ does the same but reverses the direction
819 (forward becomes backward and backward becomes forward).
820 Copy commands may take an optional buffer prefix argument which is used
822 to generate the buffer name (the default is ‘buffer’ so buffers are named
823 ‘buffer0’, ‘buffer1’ and so on). Pipe commands take a command argument
824 which is the command to which the copied text is piped. The
825 ‘-and-cancel’ variants of some commands exit copy mode after they have
826 completed (for copy commands) or when the cursor reaches the bottom (for
827 scrolling commands). ‘-no-clear’ variants do not clear the selection.
828 The next and previous word keys use space and the ‘-’, ‘_’ and ‘@’ char‐
830 acters as word delimiters by default, but this can be adjusted by setting
831 the word-separators session option. Next word moves to the start of the
832 next word, next word end to the end of the next word and previous word to
833 the start of the previous word. The three next and previous space keys
834 work similarly but use a space alone as the word separator.
835 The jump commands enable quick movement within a line. For instance,
837 typing ‘f’ followed by ‘/’ will move the cursor to the next ‘/’ character
838 on the current line. A ‘;’ will then jump to the next occurrence.
839 Commands in copy mode may be prefaced by an optional repeat count. With
841 vi key bindings, a prefix is entered using the number keys; with emacs,
842 the Alt (meta) key and a number begins prefix entry.
843 The synopsis for the copy-mode command is:
845 copy-mode [-eHMqu] [-t target-pane]
847 Enter copy mode. The -u option scrolls one page up. -M begins a
848 mouse drag (only valid if bound to a mouse key binding, see MOUSE
849 SUPPORT). -H hides the position indicator in the top right. -q
850 cancels copy mode and any other modes.
851 -e specifies that scrolling to the bottom of the history (to the
853 visible screen) should exit copy mode. While in copy mode,
854 pressing a key other than those used for scrolling will disable
855 this behaviour. This is intended to allow fast scrolling through
856 a pane's history, for example with:
857 bind PageUp copy-mode -eu
859 A number of preset arrangements of panes are available, these are called
861 layouts. These may be selected with the select-layout command or cycled
862 with next-layout (bound to ‘Space’ by default); once a layout is chosen,
863 panes within it may be moved and resized as normal.
864 The following layouts are supported:
866 even-horizontal
868 Panes are spread out evenly from left to right across the window.
869 even-vertical
871 Panes are spread evenly from top to bottom.
872 main-horizontal
874 A large (main) pane is shown at the top of the window and the
875 remaining panes are spread from left to right in the leftover
876 space at the bottom. Use the main-pane-height window option to
877 specify the height of the top pane.
878 main-vertical
880 Similar to main-horizontal but the large pane is placed on the
881 left and the others spread from top to bottom along the right.
882 See the main-pane-width window option.
883 tiled Panes are spread out as evenly as possible over the window in
885 both rows and columns.
886 In addition, select-layout may be used to apply a previously used layout
888 - the list-windows command displays the layout of each window in a form
889 suitable for use with select-layout. For example:
890 $ tmux list-windows
892 0: ksh [159x48]
893 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
894 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
895 tmux automatically adjusts the size of the layout for the current window
897 size. Note that a layout cannot be applied to a window with more panes
898 than that from which the layout was originally defined.
899 Commands related to windows and panes are as follows:
901 break-pane [-dP] [-F format] [-n window-name] [-s src-pane] [-t
903 dst-window]
904 (alias: breakp)
905 Break src-pane off from its containing window to make it the only
906 pane in dst-window. If -d is given, the new window does not
907 become the current window. The -P option prints information
908 about the new window after it has been created. By default, it
909 uses the format ‘#{session_name}:#{window_index}’ but a different
910 format may be specified with -F.
911 capture-pane [-aepPqCJN] [-b buffer-name] [-E end-line] [-S start-line]
913 [-t target-pane]
914 (alias: capturep)
915 Capture the contents of a pane. If -p is given, the output goes
916 to stdout, otherwise to the buffer specified with -b or a new
917 buffer if omitted. If -a is given, the alternate screen is used,
918 and the history is not accessible. If no alternate screen
919 exists, an error will be returned unless -q is given. If -e is
920 given, the output includes escape sequences for text and back‐
921 ground attributes. -C also escapes non-printable characters as
922 octal \xxx. -N preserves trailing spaces at each line's end and
923 -J preserves trailing spaces and joins any wrapped lines. -P
924 captures only any output that the pane has received that is the
925 beginning of an as-yet incomplete escape sequence.
926 -S and -E specify the starting and ending line numbers, zero is
928 the first line of the visible pane and negative numbers are lines
929 in the history. ‘-’ to -S is the start of the history and to -E
930 the end of the visible pane. The default is to capture only the
931 visible contents of the pane.
932 choose-client [-NrZ] [-F format] [-f filter] [-O sort-order] [-t
934 target-pane] [template]
935 Put a pane into client mode, allowing a client to be selected
936 interactively from a list. -Z zooms the pane. The following
937 keys may be used in client mode:
938 Key Function
940 Enter Choose selected client
941 Up Select previous client
942 Down Select next client
943 C-s Search by name
944 n Repeat last search
945 t Toggle if client is tagged
946 T Tag no clients
947 C-t Tag all clients
948 d Detach selected client
949 D Detach tagged clients
950 x Detach and HUP selected client
951 X Detach and HUP tagged clients
952 z Suspend selected client
953 Z Suspend tagged clients
954 f Enter a format to filter items
955 O Change sort field
956 r Reverse sort order
957 v Toggle preview
958 q Exit mode
959 After a client is chosen, ‘%%’ is replaced by the client name in
961 template and the result executed as a command. If template is
962 not given, "detach-client -t '%%'" is used.
963 -O specifies the initial sort field: one of ‘name’, ‘size’,
965 ‘creation’, or ‘activity’. -r reverses the sort order. -f spec‐
966 ifies an initial filter: the filter is a format - if it evaluates
967 to zero, the item in the list is not shown, otherwise it is
968 shown. If a filter would lead to an empty list, it is ignored.
969 -F specifies the format for each item in the list. -N starts
970 without the preview. This command works only if at least one
971 client is attached.
972 choose-tree [-GNrswZ] [-F format] [-f filter] [-O sort-order] [-t
974 target-pane] [template]
975 Put a pane into tree mode, where a session, window or pane may be
976 chosen interactively from a list. -s starts with sessions col‐
977 lapsed and -w with windows collapsed. -Z zooms the pane. The
978 following keys may be used in tree mode:
979 Key Function
981 Enter Choose selected item
982 Up Select previous item
983 Down Select next item
984 x Kill selected item
985 X Kill tagged items
986 < Scroll list of previews left
987 > Scroll list of previews right
988 C-s Search by name
989 n Repeat last search
990 t Toggle if item is tagged
991 T Tag no items
992 C-t Tag all items
993 : Run a command for each tagged item
994 f Enter a format to filter items
995 O Change sort field
996 r Reverse sort order
997 v Toggle preview
998 q Exit mode
999 After a session, window or pane is chosen, ‘%%’ is replaced by
1001 the target in template and the result executed as a command. If
1002 template is not given, "switch-client -t '%%'" is used.
1003 -O specifies the initial sort field: one of ‘index’, ‘name’, or
1005 ‘time’. -r reverses the sort order. -f specifies an initial
1006 filter: the filter is a format - if it evaluates to zero, the
1007 item in the list is not shown, otherwise it is shown. If a fil‐
1008 ter would lead to an empty list, it is ignored. -F specifies the
1009 format for each item in the tree. -N starts without the preview.
1010 -G includes all sessions in any session groups in the tree rather
1011 than only the first. This command works only if at least one
1012 client is attached.
1013 display-panes [-b] [-d duration] [-t target-client] [template]
1015 (alias: displayp)
1016 Display a visible indicator of each pane shown by target-client.
1017 See the display-panes-colour and display-panes-active-colour ses‐
1018 sion options. The indicator is closed when a key is pressed or
1019 duration milliseconds have passed. If -d is not given,
1020 display-panes-time is used. A duration of zero means the indica‐
1021 tor stays until a key is pressed. While the indicator is on
1022 screen, a pane may be chosen with the ‘0’ to ‘9’ keys, which will
1023 cause template to be executed as a command with ‘%%’ substituted
1024 by the pane ID. The default template is "select-pane -t '%%'".
1025 With -b, other commands are not blocked from running until the
1026 indicator is closed.
1027 find-window [-rCNTZ] [-t target-pane] match-string
1029 (alias: findw)
1030 Search for a fnmatch(3) pattern or, with -r, regular expression
1031 match-string in window names, titles, and visible content (but
1032 not history). The flags control matching behavior: -C matches
1033 only visible window contents, -N matches only the window name and
1034 -T matches only the window title. The default is -CNT. -Z zooms
1035 the pane.
1036 This command works only if at least one client is attached.
1038 join-pane [-bdfhv] [-l size] [-s src-pane] [-t dst-pane]
1040 (alias: joinp)
1041 Like split-window, but instead of splitting dst-pane and creating
1042 a new pane, split it and move src-pane into the space. This can
1043 be used to reverse break-pane. The -b option causes src-pane to
1044 be joined to left of or above dst-pane.
1045 If -s is omitted and a marked pane is present (see select-pane
1047 -m), the marked pane is used rather than the current pane.
1048 kill-pane [-a] [-t target-pane]
1050 (alias: killp)
1051 Destroy the given pane. If no panes remain in the containing
1052 window, it is also destroyed. The -a option kills all but the
1053 pane given with -t.
1054 kill-window [-a] [-t target-window]
1056 (alias: killw)
1057 Kill the current window or the window at target-window, removing
1058 it from any sessions to which it is linked. The -a option kills
1059 all but the window given with -t.
1060 last-pane [-deZ] [-t target-window]
1062 (alias: lastp)
1063 Select the last (previously selected) pane. -Z keeps the window
1064 zoomed if it was zoomed. -e enables or -d disables input to the
1065 pane.
1066 last-window [-t target-session]
1068 (alias: last)
1069 Select the last (previously selected) window. If no
1070 target-session is specified, select the last window of the cur‐
1071 rent session.
1072 link-window [-adk] [-s src-window] [-t dst-window]
1074 (alias: linkw)
1075 Link the window at src-window to the specified dst-window. If
1076 dst-window is specified and no such window exists, the src-window
1077 is linked there. With -a, the window is moved to the next index
1078 up (following windows are moved if necessary). If -k is given
1079 and dst-window exists, it is killed, otherwise an error is gener‐
1080 ated. If -d is given, the newly linked window is not selected.
1081 list-panes [-as] [-F format] [-t target]
1083 (alias: lsp)
1084 If -a is given, target is ignored and all panes on the server are
1085 listed. If -s is given, target is a session (or the current ses‐
1086 sion). If neither is given, target is a window (or the current
1087 window). For the meaning of the -F flag, see the FORMATS sec‐
1088 tion.
1089 list-windows [-a] [-F format] [-t target-session]
1091 (alias: lsw)
1092 If -a is given, list all windows on the server. Otherwise, list
1093 windows in the current session or in target-session. For the
1094 meaning of the -F flag, see the FORMATS section.
1095 move-pane [-bdhv] [-l size] [-s src-pane] [-t dst-pane]
1097 (alias: movep)
1098 Like join-pane, but src-pane and dst-pane may belong to the same
1099 window.
1100 move-window [-ardk] [-s src-window] [-t dst-window]
1102 (alias: movew)
1103 This is similar to link-window, except the window at src-window
1104 is moved to dst-window. With -r, all windows in the session are
1105 renumbered in sequential order, respecting the base-index option.
1106 new-window [-adkP] [-c start-directory] [-e environment] [-F format] [-n
1108 window-name] [-t target-window] [shell-command]
1109 (alias: neww)
1110 Create a new window. With -a, the new window is inserted at the
1111 next index up from the specified target-window, moving windows up
1112 if necessary, otherwise target-window is the new window location.
1113 If -d is given, the session does not make the new window the cur‐
1115 rent window. target-window represents the window to be created;
1116 if the target already exists an error is shown, unless the -k
1117 flag is used, in which case it is destroyed. shell-command is
1118 the command to execute. If shell-command is not specified, the
1119 value of the default-command option is used. -c specifies the
1120 working directory in which the new window is created.
1121 When the shell command completes, the window closes. See the
1123 remain-on-exit option to change this behaviour.
1124 -e takes the form ‘VARIABLE=value’ and sets an environment vari‐
1126 able for the newly created window; it may be specified multiple
1127 times.
1128 The TERM environment variable must be set to ‘screen’ or ‘tmux’
1130 for all programs running inside tmux. New windows will automati‐
1131 cally have ‘TERM=screen’ added to their environment, but care
1132 must be taken not to reset this in shell start-up files or by the
1133 -e option.
1134 The -P option prints information about the new window after it
1136 has been created. By default, it uses the format
1137 ‘#{session_name}:#{window_index}’ but a different format may be
1138 specified with -F.
1139 next-layout [-t target-window]
1141 (alias: nextl)
1142 Move a window to the next layout and rearrange the panes to fit.
1143 next-window [-a] [-t target-session]
1145 (alias: next)
1146 Move to the next window in the session. If -a is used, move to
1147 the next window with an alert.
1148 pipe-pane [-IOo] [-t target-pane] [shell-command]
1150 (alias: pipep)
1151 Pipe output sent by the program in target-pane to a shell command
1152 or vice versa. A pane may only be connected to one command at a
1153 time, any existing pipe is closed before shell-command is exe‐
1154 cuted. The shell-command string may contain the special charac‐
1155 ter sequences supported by the status-left option. If no
1156 shell-command is given, the current pipe (if any) is closed.
1157 -I and -O specify which of the shell-command output streams are
1159 connected to the pane: with -I stdout is connected (so anything
1160 shell-command prints is written to the pane as if it were typed);
1161 with -O stdin is connected (so any output in the pane is piped to
1162 shell-command). Both may be used together and if neither are
1163 specified, -O is used.
1164 The -o option only opens a new pipe if no previous pipe exists,
1166 allowing a pipe to be toggled with a single key, for example:
1167 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
1169 previous-layout [-t target-window]
1171 (alias: prevl)
1172 Move to the previous layout in the session.
1173 previous-window [-a] [-t target-session]
1175 (alias: prev)
1176 Move to the previous window in the session. With -a, move to the
1177 previous window with an alert.
1178 rename-window [-t target-window] new-name
1180 (alias: renamew)
1181 Rename the current window, or the window at target-window if
1182 specified, to new-name.
1183 resize-pane [-DLMRUZ] [-t target-pane] [-x width] [-y height]
1185 [adjustment]
1186 (alias: resizep)
1187 Resize a pane, up, down, left or right by adjustment with -U, -D,
1188 -L or -R, or to an absolute size with -x or -y. The adjustment
1189 is given in lines or columns (the default is 1); -x and -y may be
1190 a given as a number of lines or columns or followed by ‘%’ for a
1191 percentage of the window size (for example ‘-x 10%’). With -Z,
1192 the active pane is toggled between zoomed (occupying the whole of
1193 the window) and unzoomed (its normal position in the layout).
1194 -M begins mouse resizing (only valid if bound to a mouse key
1196 binding, see MOUSE SUPPORT).
1197 resize-window [-aADLRU] [-t target-window] [-x width] [-y height]
1199 [adjustment]
1200 (alias: resizew)
1201 Resize a window, up, down, left or right by adjustment with -U,
1202 -D, -L or -R, or to an absolute size with -x or -y. The
1203 adjustment is given in lines or cells (the default is 1). -A
1204 sets the size of the largest session containing the window; -a
1205 the size of the smallest. This command will automatically set
1206 window-size to manual in the window options.
1207 respawn-pane [-k] [-c start-directory] [-e environment] [-t target-pane]
1209 [shell-command]
1210 (alias: respawnp)
1211 Reactivate a pane in which the command has exited (see the
1212 remain-on-exit window option). If shell-command is not given,
1213 the command used when the pane was created is executed. The pane
1214 must be already inactive, unless -k is given, in which case any
1215 existing command is killed. -c specifies a new working directory
1216 for the pane. The -e option has the same meaning as for the
1217 new-window command.
1218 respawn-window [-k] [-c start-directory] [-e environment] [-t
1220 target-window] [shell-command]
1221 (alias: respawnw)
1222 Reactivate a window in which the command has exited (see the
1223 remain-on-exit window option). If shell-command is not given,
1224 the command used when the window was created is executed. The
1225 window must be already inactive, unless -k is given, in which
1226 case any existing command is killed. -c specifies a new working
1227 directory for the window. The -e option has the same meaning as
1228 for the new-window command.
1229 rotate-window [-DUZ] [-t target-window]
1231 (alias: rotatew)
1232 Rotate the positions of the panes within a window, either upward
1233 (numerically lower) with -U or downward (numerically higher). -Z
1234 keeps the window zoomed if it was zoomed.
1235 select-layout [-Enop] [-t target-pane] [layout-name]
1237 (alias: selectl)
1238 Choose a specific layout for a window. If layout-name is not
1239 given, the last preset layout used (if any) is reapplied. -n and
1240 -p are equivalent to the next-layout and previous-layout com‐
1241 mands. -o applies the last set layout if possible (undoes the
1242 most recent layout change). -E spreads the current pane and any
1243 panes next to it out evenly.
1244 select-pane [-DdeLlMmRUZ] [-T title] [-t target-pane]
1246 (alias: selectp)
1247 Make pane target-pane the active pane in window target-window.
1248 If one of -D, -L, -R, or -U is used, respectively the pane below,
1249 to the left, to the right, or above the target pane is used. -Z
1250 keeps the window zoomed if it was zoomed. -l is the same as
1251 using the last-pane command. -e enables or -d disables input to
1252 the pane. -T sets the pane title.
1253 -m and -M are used to set and clear the marked pane. There is
1255 one marked pane at a time, setting a new marked pane clears the
1256 last. The marked pane is the default target for -s to join-pane,
1257 swap-pane and swap-window.
1258 select-window [-lnpT] [-t target-window]
1260 (alias: selectw)
1261 Select the window at target-window. -l, -n and -p are equivalent
1262 to the last-window, next-window and previous-window commands. If
1263 -T is given and the selected window is already the current win‐
1264 dow, the command behaves like last-window.
1265 split-window [-bdfhIvP] [-c start-directory] [-e environment] [-l size]
1267 [-t target-pane] [shell-command] [-F format]
1268 (alias: splitw)
1269 Create a new pane by splitting target-pane: -h does a horizontal
1270 split and -v a vertical split; if neither is specified, -v is
1271 assumed. The -l option specifies the size of the new pane in
1272 lines (for vertical split) or in columns (for horizontal split);
1273 size may be followed by ‘%’ to specify a percentage of the avail‐
1274 able space. The -b option causes the new pane to be created to
1275 the left of or above target-pane. The -f option creates a new
1276 pane spanning the full window height (with -h) or full window
1277 width (with -v), instead of splitting the active pane.
1278 An empty shell-command ('') will create a pane with no command
1280 running in it. Output can be sent to such a pane with the
1281 display-message command. The -I flag (if shell-command is not
1282 specified or empty) will create an empty pane and forward any
1283 output from stdin to it. For example:
1284 $ make 2>&1|tmux splitw -dI &
1286 All other options have the same meaning as for the new-window
1288 command.
1289 swap-pane [-dDUZ] [-s src-pane] [-t dst-pane]
1291 (alias: swapp)
1292 Swap two panes. If -U is used and no source pane is specified
1293 with -s, dst-pane is swapped with the previous pane (before it
1294 numerically); -D swaps with the next pane (after it numerically).
1295 -d instructs tmux not to change the active pane and -Z keeps the
1296 window zoomed if it was zoomed.
1297 If -s is omitted and a marked pane is present (see select-pane
1299 -m), the marked pane is used rather than the current pane.
1300 swap-window [-d] [-s src-window] [-t dst-window]
1302 (alias: swapw)
1303 This is similar to link-window, except the source and destination
1304 windows are swapped. It is an error if no window exists at
1305 src-window. If -d is given, the new window does not become the
1306 current window.
1307 If -s is omitted and a marked pane is present (see select-pane
1309 -m), the window containing the marked pane is used rather than
1310 the current window.
1311 unlink-window [-k] [-t target-window]
1313 (alias: unlinkw)
1314 Unlink target-window. Unless -k is given, a window may be
1315 unlinked only if it is linked to multiple sessions - windows may
1316 not be linked to no sessions; if -k is specified and the window
1317 is linked to only one session, it is unlinked and destroyed.
1318
1320 tmux allows a command to be bound to most keys, with or without a prefix
1321 key. When specifying keys, most represent themselves (for example ‘A’ to
1322 ‘Z’). Ctrl keys may be prefixed with ‘C-’ or ‘^’, and Alt (meta) with
1323 ‘M-’. In addition, the following special key names are accepted: Up,
1324 Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to
1325 F12, Home, IC (Insert), NPage/PageDown/PgDn, PPage/PageUp/PgUp, Space,
1326 and Tab. Note that to bind the ‘"’ or ‘'’ keys, quotation marks are nec‐
1327 essary, for example:
1328 bind-key '"' split-window
1330 bind-key "'" new-window
1331 A command bound to the Any key will execute for all keys which do not
1333 have a more specific binding.
1334 Commands related to key bindings are as follows:
1336 bind-key [-nr] [-N note] [-T key-table] key command [arguments]
1338 (alias: bind)
1339 Bind key key to command. Keys are bound in a key table. By
1340 default (without -T), the key is bound in the prefix key table.
1341 This table is used for keys pressed after the prefix key (for
1342 example, by default ‘c’ is bound to new-window in the prefix ta‐
1343 ble, so ‘C-b c’ creates a new window). The root table is used
1344 for keys pressed without the prefix key: binding ‘c’ to
1345 new-window in the root table (not recommended) means a plain ‘c’
1346 will create a new window. -n is an alias for -T root. Keys may
1347 also be bound in custom key tables and the switch-client -T com‐
1348 mand used to switch to them from a key binding. The -r flag
1349 indicates this key may repeat, see the repeat-time option. -N
1350 attaches a note to the key (shown with list-keys -N).
1351 To view the default bindings and possible commands, see the
1353 list-keys command.
1354 list-keys [-1aN] [-P prefix-string -T key-table] [key]
1356 (alias: lsk)
1357 List key bindings. There are two forms: the default lists keys
1358 as bind-key commands; -N lists only keys with attached notes and
1359 shows only the key and note for each key.
1360 With the default form, all key tables are listed by default. -T
1362 lists only keys in key-table.
1363 With the -N form, only keys in the root and prefix key tables are
1365 listed by default; -T also lists only keys in key-table. -P
1366 specifies a prefix to print before each key and -1 lists only the
1367 first matching key. -a lists the command for keys that do have a
1368 note rather than skipping them.
1369 send-keys [-FHlMRX] [-N repeat-count] [-t target-pane] key ...
1371 (alias: send)
1372 Send a key or keys to a window. Each argument key is the name of
1373 the key (such as ‘C-a’ or ‘NPage’) to send; if the string is not
1374 recognised as a key, it is sent as a series of characters. All
1375 arguments are sent sequentially from first to last.
1376 The -l flag disables key name lookup and processes the keys as
1378 literal UTF-8 characters. The -H flag expects each key to be a
1379 hexadecimal number for an ASCII character.
1380 The -R flag causes the terminal state to be reset.
1382 -M passes through a mouse event (only valid if bound to a mouse
1384 key binding, see MOUSE SUPPORT).
1385 -X is used to send a command into copy mode - see the WINDOWS AND
1387 PANES section. -N specifies a repeat count and -F expands for‐
1388 mats in arguments where appropriate.
1389 send-prefix [-2] [-t target-pane]
1391 Send the prefix key, or with -2 the secondary prefix key, to a
1392 window as if it was pressed.
1393 unbind-key [-an] [-T key-table] key
1395 (alias: unbind)
1396 Unbind the command bound to key. -n and -T are the same as for
1397 bind-key. If -a is present, all key bindings are removed.
1398
1400 The appearance and behaviour of tmux may be modified by changing the
1401 value of various options. There are four types of option: server
1402 options, session options window options and pane options.
1403 The tmux server has a set of global server options which do not apply to
1405 any particular window or session or pane. These are altered with the
1406 set-option -s command, or displayed with the show-options -s command.
1407 In addition, each individual session may have a set of session options,
1409 and there is a separate set of global session options. Sessions which do
1410 not have a particular option configured inherit the value from the global
1411 session options. Session options are set or unset with the set-option
1412 command and may be listed with the show-options command. The available
1413 server and session options are listed under the set-option command.
1414 Similarly, a set of window options is attached to each window and a set
1416 of pane options to each pane. Pane options inherit from window options.
1417 This means any pane option may be set as a window option to apply the
1418 option to all panes in the window without the option set, for example
1419 these commands will set the background colour to red for all panes except
1420 pane 0:
1421 set -w window-style bg=red
1423 set -pt:.0 window-style bg=blue
1424 There is also a set of global window options from which any unset window
1426 or pane options are inherited. Window and pane options are altered with
1427 set-option -w and -p commands and displayed with show-option -w and -p.
1428 tmux also supports user options which are prefixed with a ‘@’. User
1430 options may have any name, so long as they are prefixed with ‘@’, and be
1431 set to any string. For example:
1432 $ tmux setw -q @foo "abc123"
1434 $ tmux showw -v @foo
1435 abc123
1436 Commands which set options are as follows:
1438 set-option [-aFgopqsuw] [-t target-pane] option value
1440 (alias: set)
1441 Set a pane option with -p, a window option with -w, a server
1442 option with -s, otherwise a session option. If the option is not
1443 a user option, -w or -s may be unnecessary - tmux will infer the
1444 type from the option name, assuming -w for pane options. If -g
1445 is given, the global session or window option is set.
1446 -F expands formats in the option value. The -u flag unsets an
1448 option, so a session inherits the option from the global options
1449 (or with -g, restores a global option to the default).
1450 The -o flag prevents setting an option that is already set and
1452 the -q flag suppresses errors about unknown or ambiguous options.
1453 With -a, and if the option expects a string or a style, value is
1455 appended to the existing setting. For example:
1456 set -g status-left "foo"
1458 set -ag status-left "bar"
1459 Will result in ‘foobar’. And:
1461 set -g status-style "bg=red"
1463 set -ag status-style "fg=blue"
1464 Will result in a red background and blue foreground. Without -a,
1466 the result would be the default background and a blue foreground.
1467 show-options [-AgHpqsvw] [-t target-pane] [option]
1469 (alias: show)
1470 Show the pane options (or a single option if option is provided)
1471 with -p, the window options with -w, the server options with -s,
1472 otherwise the session options. If the option is not a user
1473 option, -w or -s may be unnecessary - tmux will infer the type
1474 from the option name, assuming -w for pane options. Global ses‐
1475 sion or window options are listed if -g is used. -v shows only
1476 the option value, not the name. If -q is set, no error will be
1477 returned if option is unset. -H includes hooks (omitted by
1478 default). -A includes options inherited from a parent set of
1479 options, such options are marked with an asterisk. value depends
1480 on the option and may be a number, a string, or a flag (on, off,
1481 or omitted to toggle).
1482 Available server options are:
1484 backspace key
1486 Set the key sent by tmux for backspace.
1487 buffer-limit number
1489 Set the number of buffers; as new buffers are added to the top of
1490 the stack, old ones are removed from the bottom if necessary to
1491 maintain this maximum length.
1492 command-alias[] name=value
1494 This is an array of custom aliases for commands. If an unknown
1495 command matches name, it is replaced with value. For example,
1496 after:
1497 set -s command-alias[100] zoom='resize-pane -Z'
1499 Using:
1501 zoom -t:.1
1503 Is equivalent to:
1505 resize-pane -Z -t:.1
1507 Note that aliases are expanded when a command is parsed rather
1509 than when it is executed, so binding an alias with bind-key will
1510 bind the expanded form.
1511 default-terminal terminal
1513 Set the default terminal for new windows created in this session
1514 - the default value of the TERM environment variable. For tmux
1515 to work correctly, this must be set to ‘screen’, ‘tmux’ or a de‐
1516 rivative of them.
1517 escape-time time
1519 Set the time in milliseconds for which tmux waits after an escape
1520 is input to determine if it is part of a function or meta key
1521 sequences. The default is 500 milliseconds.
1522 exit-empty [on | off]
1524 If enabled (the default), the server will exit when there are no
1525 active sessions.
1526 exit-unattached [on | off]
1528 If enabled, the server will exit when there are no attached
1529 clients.
1530 focus-events [on | off]
1532 When enabled, focus events are requested from the terminal if
1533 supported and passed through to applications running in tmux.
1534 Attached clients should be detached and attached again after
1535 changing this option.
1536 history-file path
1538 If not empty, a file to which tmux will write command prompt his‐
1539 tory on exit and load it from on start.
1540 message-limit number
1542 Set the number of error or information messages to save in the
1543 message log for each client. The default is 100.
1544 set-clipboard [on | external | off]
1546 Attempt to set the terminal clipboard content using the xterm(1)
1547 escape sequence, if there is an Ms entry in the terminfo(5)
1548 description (see the TERMINFO EXTENSIONS section).
1549 If set to on, tmux will both accept the escape sequence to create
1551 a buffer and attempt to set the terminal clipboard. If set to
1552 external, tmux will attempt to set the terminal clipboard but
1553 ignore attempts by applications to set tmux buffers. If off,
1554 tmux will neither accept the clipboard escape sequence nor
1555 attempt to set the clipboard.
1556 Note that this feature needs to be enabled in xterm(1) by setting
1558 the resource:
1559 disallowedWindowOps: 20,21,SetXprop
1561 Or changing this property from the xterm(1) interactive menu when
1563 required.
1564 terminal-overrides[] string
1566 Allow terminal descriptions read using terminfo(5) to be overrid‐
1567 den. Each entry is a colon-separated string made up of a termi‐
1568 nal type pattern (matched using fnmatch(3)) and a set of
1569 name=value entries.
1570 For example, to set the ‘clear’ terminfo(5) entry to ‘\e[H\e[2J’
1572 for all terminal types matching ‘rxvt*’:
1573 rxvt*:clear=\e[H\e[2J
1575 The terminal entry value is passed through strunvis(3) before
1577 interpretation.
1578 user-keys[] key
1580 Set list of user-defined key escape sequences. Each item is
1581 associated with a key named ‘User0’, ‘User1’, and so on.
1582 For example:
1584 set -s user-keys[0] "\e[5;30012~"
1586 bind User0 resize-pane -L 3
1587 Available session options are:
1589 activity-action [any | none | current | other]
1591 Set action on window activity when monitor-activity is on. any
1592 means activity in any window linked to a session causes a bell or
1593 message (depending on visual-activity) in the current window of
1594 that session, none means all activity is ignored (equivalent to
1595 monitor-activity being off), current means only activity in win‐
1596 dows other than the current window are ignored and other means
1597 activity in the current window is ignored but not those in other
1598 windows.
1599 assume-paste-time milliseconds
1601 If keys are entered faster than one in milliseconds, they are
1602 assumed to have been pasted rather than typed and tmux key bind‐
1603 ings are not processed. The default is one millisecond and zero
1604 disables.
1605 base-index index
1607 Set the base index from which an unused index should be searched
1608 when a new window is created. The default is zero.
1609 bell-action [any | none | current | other]
1611 Set action on a bell in a window when monitor-bell is on. The
1612 values are the same as those for activity-action.
1613 default-command shell-command
1615 Set the command used for new windows (if not specified when the
1616 window is created) to shell-command, which may be any sh(1) com‐
1617 mand. The default is an empty string, which instructs tmux to
1618 create a login shell using the value of the default-shell option.
1619 default-shell path
1621 Specify the default shell. This is used as the login shell for
1622 new windows when the default-command option is set to empty, and
1623 must be the full path of the executable. When started tmux tries
1624 to set a default value from the first suitable of the SHELL envi‐
1625 ronment variable, the shell returned by getpwuid(3), or /bin/sh.
1626 This option should be configured when tmux is used as a login
1627 shell.
1628 default-size XxY
1630 Set the default size of new windows when the window-size option
1631 is set to manual or when a session is created with new-session
1632 -d. The value is the width and height separated by an ‘x’ char‐
1633 acter. The default is 80x24.
1634 destroy-unattached [on | off]
1636 If enabled and the session is no longer attached to any clients,
1637 it is destroyed.
1638 detach-on-destroy [on | off]
1640 If on (the default), the client is detached when the session it
1641 is attached to is destroyed. If off, the client is switched to
1642 the most recently active of the remaining sessions.
1643 display-panes-active-colour colour
1645 Set the colour used by the display-panes command to show the
1646 indicator for the active pane.
1647 display-panes-colour colour
1649 Set the colour used by the display-panes command to show the
1650 indicators for inactive panes.
1651 display-panes-time time
1653 Set the time in milliseconds for which the indicators shown by
1654 the display-panes command appear.
1655 display-time time
1657 Set the amount of time for which status line messages and other
1658 on-screen indicators are displayed. If set to 0, messages and
1659 indicators are displayed until a key is pressed. time is in mil‐
1660 liseconds.
1661 history-limit lines
1663 Set the maximum number of lines held in window history. This
1664 setting applies only to new windows - existing window histories
1665 are not resized and retain the limit at the point they were cre‐
1666 ated.
1667 key-table key-table
1669 Set the default key table to key-table instead of root.
1670 lock-after-time number
1672 Lock the session (like the lock-session command) after number
1673 seconds of inactivity. The default is not to lock (set to 0).
1674 lock-command shell-command
1676 Command to run when locking each client. The default is to run
1677 lock(1) with -np.
1678 message-command-style style
1680 Set status line message command style. For how to specify style,
1681 see the STYLES section.
1682 message-style style
1684 Set status line message style. For how to specify style, see the
1685 STYLES section.
1686 mouse [on | off]
1688 If on, tmux captures the mouse and allows mouse events to be
1689 bound as key bindings. See the MOUSE SUPPORT section for
1690 details.
1691 prefix key
1693 Set the key accepted as a prefix key. In addition to the stan‐
1694 dard keys described under KEY BINDINGS, prefix can be set to the
1695 special key ‘None’ to set no prefix.
1696 prefix2 key
1698 Set a secondary key accepted as a prefix key. Like prefix,
1699 prefix2 can be set to ‘None’.
1700 renumber-windows [on | off]
1702 If on, when a window is closed in a session, automatically renum‐
1703 ber the other windows in numerical order. This respects the
1704 base-index option if it has been set. If off, do not renumber
1705 the windows.
1706 repeat-time time
1708 Allow multiple commands to be entered without pressing the pre‐
1709 fix-key again in the specified time milliseconds (the default is
1710 500). Whether a key repeats may be set when it is bound using
1711 the -r flag to bind-key. Repeat is enabled for the default keys
1712 bound to the resize-pane command.
1713 set-titles [on | off]
1715 Attempt to set the client terminal title using the tsl and fsl
1716 terminfo(5) entries if they exist. tmux automatically sets these
1717 to the \e]0;...\007 sequence if the terminal appears to be
1718 xterm(1). This option is off by default.
1719 set-titles-string string
1721 String used to set the client terminal title if set-titles is on.
1722 Formats are expanded, see the FORMATS section.
1723 silence-action [any | none | current | other]
1725 Set action on window silence when monitor-silence is on. The
1726 values are the same as those for activity-action.
1727 status [off | on | 2 | 3 | 4 | 5]
1729 Show or hide the status line or specify its size. Using on gives
1730 a status line one row in height; 2, 3, 4 or 5 more rows.
1731 status-format[] format
1733 Specify the format to be used for each line of the status line.
1734 The default builds the top status line from the various individ‐
1735 ual status options below.
1736 status-interval interval
1738 Update the status line every interval seconds. By default,
1739 updates will occur every 15 seconds. A setting of zero disables
1740 redrawing at interval.
1741 status-justify [left | centre | right]
1743 Set the position of the window list component of the status line:
1744 left, centre or right justified.
1745 status-keys [vi | emacs]
1747 Use vi or emacs-style key bindings in the status line, for exam‐
1748 ple at the command prompt. The default is emacs, unless the
1749 VISUAL or EDITOR environment variables are set and contain the
1750 string ‘vi’.
1751 status-left string
1753 Display string (by default the session name) to the left of the
1754 status line. string will be passed through strftime(3). Also
1755 see the FORMATS and STYLES sections.
1756 For details on how the names and titles can be set see the NAMES
1758 AND TITLES section.
1759 Examples are:
1761 #(sysctl vm.loadavg)
1763 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
1764 The default is ‘[#S] ’.
1766 status-left-length length
1768 Set the maximum length of the left component of the status line.
1769 The default is 10.
1770 status-left-style style
1772 Set the style of the left part of the status line. For how to
1773 specify style, see the STYLES section.
1774 status-position [top | bottom]
1776 Set the position of the status line.
1777 status-right string
1779 Display string to the right of the status line. By default, the
1780 current pane title in double quotes, the date and the time are
1781 shown. As with status-left, string will be passed to strftime(3)
1782 and character pairs are replaced.
1783 status-right-length length
1785 Set the maximum length of the right component of the status line.
1786 The default is 40.
1787 status-right-style style
1789 Set the style of the right part of the status line. For how to
1790 specify style, see the STYLES section.
1791 status-style style
1793 Set status line style. For how to specify style, see the STYLES
1794 section.
1795 update-environment[] variable
1797 Set list of environment variables to be copied into the session
1798 environment when a new session is created or an existing session
1799 is attached. Any variables that do not exist in the source envi‐
1800 ronment are set to be removed from the session environment (as if
1801 -r was given to the set-environment command).
1802 visual-activity [on | off | both]
1804 If on, display a message instead of sending a bell when activity
1805 occurs in a window for which the monitor-activity window option
1806 is enabled. If set to both, a bell and a message are produced.
1807 visual-bell [on | off | both]
1809 If on, a message is shown on a bell in a window for which the
1810 monitor-bell window option is enabled instead of it being passed
1811 through to the terminal (which normally makes a sound). If set
1812 to both, a bell and a message are produced. Also see the
1813 bell-action option.
1814 visual-silence [on | off | both]
1816 If monitor-silence is enabled, prints a message after the inter‐
1817 val has expired on a given window instead of sending a bell. If
1818 set to both, a bell and a message are produced.
1819 word-separators string
1821 Sets the session's conception of what characters are considered
1822 word separators, for the purposes of the next and previous word
1823 commands in copy mode. The default is ‘ -_@’.
1824 Available window options are:
1826 aggressive-resize [on | off]
1828 Aggressively resize the chosen window. This means that tmux will
1829 resize the window to the size of the smallest or largest session
1830 (see the window-size option) for which it is the current window,
1831 rather than the session to which it is attached. The window may
1832 resize when the current window is changed on another session;
1833 this option is good for full-screen programs which support
1834 SIGWINCH and poor for interactive programs such as shells.
1835 automatic-rename [on | off]
1837 Control automatic window renaming. When this setting is enabled,
1838 tmux will rename the window automatically using the format speci‐
1839 fied by automatic-rename-format. This flag is automatically dis‐
1840 abled for an individual window when a name is specified at cre‐
1841 ation with new-window or new-session, or later with
1842 rename-window, or with a terminal escape sequence. It may be
1843 switched off globally with:
1844 set-option -wg automatic-rename off
1846 automatic-rename-format format
1848 The format (see FORMATS) used when the automatic-rename option is
1849 enabled.
1850 clock-mode-colour colour
1852 Set clock colour.
1853 clock-mode-style [12 | 24]
1855 Set clock hour format.
1856 main-pane-height height
1858 main-pane-width width
1859 Set the width or height of the main (left or top) pane in the
1860 main-horizontal or main-vertical layouts.
1861 mode-keys [vi | emacs]
1863 Use vi or emacs-style key bindings in copy mode. The default is
1864 emacs, unless VISUAL or EDITOR contains ‘vi’.
1865 mode-style style
1867 Set window modes style. For how to specify style, see the STYLES
1868 section.
1869 monitor-activity [on | off]
1871 Monitor for activity in the window. Windows with activity are
1872 highlighted in the status line.
1873 monitor-bell [on | off]
1875 Monitor for a bell in the window. Windows with a bell are high‐
1876 lighted in the status line.
1877 monitor-silence [interval]
1879 Monitor for silence (no activity) in the window within interval
1880 seconds. Windows that have been silent for the interval are
1881 highlighted in the status line. An interval of zero disables the
1882 monitoring.
1883 other-pane-height height
1885 Set the height of the other panes (not the main pane) in the
1886 main-horizontal layout. If this option is set to 0 (the
1887 default), it will have no effect. If both the main-pane-height
1888 and other-pane-height options are set, the main pane will grow
1889 taller to make the other panes the specified height, but will
1890 never shrink to do so.
1891 other-pane-width width
1893 Like other-pane-height, but set the width of other panes in the
1894 main-vertical layout.
1895 pane-active-border-style style
1897 Set the pane border style for the currently active pane. For how
1898 to specify style, see the STYLES section. Attributes are
1899 ignored.
1900 pane-base-index index
1902 Like base-index, but set the starting index for pane numbers.
1903 pane-border-format format
1905 Set the text shown in pane border status lines.
1906 pane-border-status [off | top | bottom]
1908 Turn pane border status lines off or set their position.
1909 pane-border-style style
1911 Set the pane border style for panes aside from the active pane.
1912 For how to specify style, see the STYLES section. Attributes are
1913 ignored.
1914 synchronize-panes [on | off]
1916 Duplicate input to any pane to all other panes in the same window
1917 (only for panes that are not in any special mode).
1918 window-status-activity-style style
1920 Set status line style for windows with an activity alert. For
1921 how to specify style, see the STYLES section.
1922 window-status-bell-style style
1924 Set status line style for windows with a bell alert. For how to
1925 specify style, see the STYLES section.
1926 window-status-current-format string
1928 Like window-status-format, but is the format used when the window
1929 is the current window.
1930 window-status-current-style style
1932 Set status line style for the currently active window. For how
1933 to specify style, see the STYLES section.
1934 window-status-format string
1936 Set the format in which the window is displayed in the status
1937 line window list. See the FORMATS and STYLES sections.
1938 window-status-last-style style
1940 Set status line style for the last active window. For how to
1941 specify style, see the STYLES section.
1942 window-status-separator string
1944 Sets the separator drawn between windows in the status line. The
1945 default is a single space character.
1946 window-status-style style
1948 Set status line style for a single window. For how to specify
1949 style, see the STYLES section.
1950 window-size largest | smallest | manual | latest
1952 Configure how tmux determines the window size. If set to
1953 largest, the size of the largest attached session is used; if
1954 smallest, the size of the smallest. If manual, the size of a new
1955 window is set from the default-size option and windows are
1956 resized automatically. With latest, tmux uses the size of the
1957 client that had the most recent activity. See also the
1958 resize-window command and the aggressive-resize option.
1959 wrap-search [on | off]
1961 If this option is set, searches will wrap around the end of the
1962 pane contents. The default is on.
1963 xterm-keys [on | off]
1965 If this option is set, tmux will generate xterm(1) -style func‐
1966 tion key sequences; these have a number included to indicate mod‐
1967 ifiers such as Shift, Alt or Ctrl.
1968 Available pane options are:
1970 allow-rename [on | off]
1972 Allow programs in the pane to change the window name using a ter‐
1973 minal escape sequence (\ek...\e\\).
1974 alternate-screen [on | off]
1976 This option configures whether programs running inside the pane
1977 may use the terminal alternate screen feature, which allows the
1978 smcup and rmcup terminfo(5) capabilities. The alternate screen
1979 feature preserves the contents of the window when an interactive
1980 application starts and restores it on exit, so that any output
1981 visible before the application starts reappears unchanged after
1982 it exits.
1983 remain-on-exit [on | off]
1985 A pane with this flag set is not destroyed when the program run‐
1986 ning in it exits. The pane may be reactivated with the
1987 respawn-pane command.
1988 window-active-style style
1990 Set the pane style when it is the active pane. For how to spec‐
1991 ify style, see the STYLES section.
1992 window-style style
1994 Set the pane style. For how to specify style, see the STYLES
1995 section.
1996
1998 tmux allows commands to run on various triggers, called hooks. Most tmux
1999 commands have an after hook and there are a number of hooks not associ‐
2000 ated with commands.
2001 Hooks are stored as array options, members of the array are executed in
2003 order when the hook is triggered. Hooks may be configured with the
2004 set-hook or set-option commands and displayed with show-hooks or
2005 show-options -H. The following two commands are equivalent:
2006 set-hook -g pane-mode-changed[42] 'set -g status-left-style bg=red'
2008 set-option -g pane-mode-changed[42] 'set -g status-left-style bg=red'
2009 Setting a hook without specifying an array index clears the hook and sets
2011 the first member of the array.
2012 A command's after hook is run after it completes, except when the command
2014 is run as part of a hook itself. They are named with an ‘after-’ prefix.
2015 For example, the following command adds a hook to select the even-verti‐
2016 cal layout after every split-window:
2017 set-hook -g after-split-window "selectl even-vertical"
2019 All the notifications listed in the CONTROL MODE section are hooks (with‐
2021 out any arguments), except %exit. The following additional hooks are
2022 available:
2023 alert-activity Run when a window has activity. See
2025 monitor-activity.
2026 alert-bell Run when a window has received a bell. See
2028 monitor-bell.
2029 alert-silence Run when a window has been silent. See
2031 monitor-silence.
2032 client-attached Run when a client is attached.
2034 client-detached Run when a client is detached
2036 client-resized Run when a client is resized.
2038 client-session-changed Run when a client's attached session is changed.
2040 pane-died Run when the program running in a pane exits, but
2042 remain-on-exit is on so the pane has not closed.
2043 pane-exited Run when the program running in a pane exits.
2045 pane-focus-in Run when the focus enters a pane, if the
2047 focus-events option is on.
2048 pane-focus-out Run when the focus exits a pane, if the
2050 focus-events option is on.
2051 pane-set-clipboard Run when the terminal clipboard is set using the
2053 xterm(1) escape sequence.
2054 session-created Run when a new session created.
2056 session-closed Run when a session closed.
2058 session-renamed Run when a session is renamed.
2060 window-linked Run when a window is linked into a session.
2062 window-renamed Run when a window is renamed.
2064 window-unlinked Run when a window is unlinked from a session.
2066 Hooks are managed with these commands:
2068 set-hook [-agRu] [-t target-session] hook-name command
2070 Without -R, sets (or with -u unsets) hook hook-name to command.
2071 If -g is given, hook-name is added to the global list of hooks,
2072 otherwise it is added to the session hooks (for target-session
2073 with -t). -a appends to a hook. Like options, session hooks
2074 inherit from the global ones.
2075 With -R, run hook-name immediately.
2077 show-hooks [-g] [-t target-session]
2079 Shows the global list of hooks with -g, otherwise the session
2080 hooks.
2081
2083 If the mouse option is on (the default is off), tmux allows mouse events
2084 to be bound as keys. The name of each key is made up of a mouse event
2085 (such as ‘MouseUp1’) and a location suffix, one of the following:
2086 Pane the contents of a pane
2088 Border a pane border
2089 Status the status line window list
2090 StatusLeft the left part of the status line
2091 StatusRight the right part of the status line
2092 StatusDefault any other part of the status line
2093 The following mouse events are available:
2095 WheelUp WheelDown
2097 MouseDown1 MouseUp1 MouseDrag1 MouseDragEnd1
2098 MouseDown2 MouseUp2 MouseDrag2 MouseDragEnd2
2099 MouseDown3 MouseUp3 MouseDrag3 MouseDragEnd3
2100 DoubleClick1 DoubleClick2 DoubleClick3
2101 TripleClick1 TripleClick2 TripleClick3
2102 Each should be suffixed with a location, for example ‘MouseDown1Status’.
2104 The special token ‘{mouse}’ or ‘=’ may be used as target-window or
2106 target-pane in commands bound to mouse key bindings. It resolves to the
2107 window or pane over which the mouse event took place (for example, the
2108 window in the status line over which button 1 was released for a
2109 ‘MouseUp1Status’ binding, or the pane over which the wheel was scrolled
2110 for a ‘WheelDownPane’ binding).
2111 The send-keys -M flag may be used to forward a mouse event to a pane.
2113 The default key bindings allow the mouse to be used to select and resize
2115 panes, to copy text and to change window using the status line. These
2116 take effect if the mouse option is turned on.
2117
2119 Certain commands accept the -F flag with a format argument. This is a
2120 string which controls the output format of the command. Format variables
2121 are enclosed in ‘#{’ and ‘}’, for example ‘#{session_name}’. The possi‐
2122 ble variables are listed in the table below, or the name of a tmux option
2123 may be used for an option's value. Some variables have a shorter alias
2124 such as ‘#S’; ‘##’ is replaced by a single ‘#’, ‘#,’ by a ‘,’ and ‘#}’ by
2125 a ‘}’.
2126 Conditionals are available by prefixing with ‘?’ and separating two
2128 alternatives with a comma; if the specified variable exists and is not
2129 zero, the first alternative is chosen, otherwise the second is used. For
2130 example ‘#{?session_attached,attached,not attached}’ will include the
2131 string ‘attached’ if the session is attached and the string ‘not
2132 attached’ if it is unattached, or ‘#{?automatic-rename,yes,no}’ will
2133 include ‘yes’ if automatic-rename is enabled, or ‘no’ if not. Condition‐
2134 als can be nested arbitrarily. Inside a conditional, ‘,’ and ‘}’ must be
2135 escaped as ‘#,’ and ‘#}’, unless they are part of a ‘#{...}’ replacement.
2136 For example:
2137 #{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W .
2139 String comparisons may be expressed by prefixing two comma-separated
2141 alternatives by ‘==’, ‘!=’, ‘<’, ‘>’, ‘<=’ or ‘>=’ and a colon. For
2142 example ‘#{==:#{host},myhost}’ will be replaced by ‘1’ if running on
2143 ‘myhost’, otherwise by ‘0’. ‘||’ and ‘&&’ evaluate to true if either or
2144 both of two comma-separated alternatives are true, for example
2145 ‘#{||:#{pane_in_mode},#{alternate_on}}’.
2146 An ‘m’ specifies an fnmatch(3) or regular expression comparison. The
2148 first argument is the pattern and the second the string to compare. An
2149 optional third argument specifies flags: ‘r’ means the pattern is a regu‐
2150 lar expression instead of the default fnmatch(3) pattern, and ‘i’ means
2151 to ignore case. For example: ‘#{m:*foo*,#{host}}’ or ‘#{m/ri:^A,MYVAR}’.
2152 A ‘C’ performs a search for an fnmatch(3) pattern or regular expression
2153 in the pane content and evaluates to zero if not found, or a line number
2154 if found. Like ‘m’, an ‘r’ flag means search for a regular expression
2155 and ‘i’ ignores case. For example: ‘#{C/r:^Start}’
2156 A limit may be placed on the length of the resultant string by prefixing
2158 it by an ‘=’, a number and a colon. Positive numbers count from the
2159 start of the string and negative from the end, so ‘#{=5:pane_title}’ will
2160 include at most the first five characters of the pane title, or
2161 ‘#{=-5:pane_title}’ the last five characters. A suffix or prefix may be
2162 given as a second argument - if provided then it is appended or prepended
2163 to the string if the length has been trimmed, for example
2164 ‘#{=/5/...:pane_title}’ will append ‘...’ if the pane title is more than
2165 five characters. Similarly, ‘p’ pads the string to a given width, for
2166 example ‘#{p10:pane_title}’ will result in a width of at least 10 charac‐
2167 ters. A positive width pads on the left, a negative on the right.
2168 Prefixing a time variable with ‘t:’ will convert it to a string, so if
2170 ‘#{window_activity}’ gives ‘1445765102’, ‘#{t:window_activity}’ gives
2171 ‘Sun Oct 25 09:25:02 2015’. The ‘b:’ and ‘d:’ prefixes are basename(3)
2172 and dirname(3) of the variable respectively. ‘q:’ will escape sh(1) spe‐
2173 cial characters. ‘E:’ will expand the format twice, for example
2174 ‘#{E:status-left}’ is the result of expanding the content of the
2175 status-left option rather than the option itself. ‘T:’ is like ‘E:’ but
2176 also expands strftime(3) specifiers. ‘S:’, ‘W:’ or ‘P:’ will loop over
2177 each session, window or pane and insert the format once for each. For
2178 windows and panes, two comma-separated formats may be given: the second
2179 is used for the current window or active pane. For example, to get a
2180 list of windows formatted like the status line:
2181 #{W:#{E:window-status-format} ,#{E:window-status-current-format} }
2183 A prefix of the form ‘s/foo/bar/:’ will substitute ‘foo’ with ‘bar’
2185 throughout. The first argument may be an extended regular expression and
2186 a final argument may be ‘i’ to ignore case, for example ‘s/a(.)/\1x/i:’
2187 would change ‘abABab’ into ‘bxBxbx’.
2188 In addition, the last line of a shell command's output may be inserted
2190 using ‘#()’. For example, ‘#(uptime)’ will insert the system's uptime.
2191 When constructing formats, tmux does not wait for ‘#()’ commands to fin‐
2192 ish; instead, the previous result from running the same command is used,
2193 or a placeholder if the command has not been run before. If the command
2194 hasn't exited, the most recent line of output will be used, but the sta‐
2195 tus line will not be updated more than once a second. Commands are exe‐
2196 cuted with the tmux global environment set (see the GLOBAL AND SESSION
2197 ENVIRONMENT section).
2198 An ‘l’ specifies that a string should be interpreted literally and not
2200 expanded. For example ‘#{l:#{?pane_in_mode,yes,no}}’ will be replaced by
2201 ‘#{?pane_in_mode,yes,no}’.
2202 The following variables are available, where appropriate:
2204 Variable name Alias Replaced with
2206 alternate_on 1 if pane is in alternate screen
2207 alternate_saved_x Saved cursor X in alternate screen
2208 alternate_saved_y Saved cursor Y in alternate screen
2209 buffer_created Time buffer created
2210 buffer_name Name of buffer
2211 buffer_sample Sample of start of buffer
2212 buffer_size Size of the specified buffer in bytes
2213 client_activity Time client last had activity
2214 client_cell_height Height of each client cell in pixels
2215 client_cell_width Width of each client cell in pixels
2216 client_control_mode 1 if client is in control mode
2217 client_created Time client created
2218 client_discarded Bytes discarded when client behind
2219 client_height Height of client
2220 client_key_table Current key table
2221 client_last_session Name of the client's last session
2222 client_name Name of client
2223 client_pid PID of client process
2224 client_prefix 1 if prefix key has been pressed
2225 client_readonly 1 if client is readonly
2226 client_session Name of the client's session
2227 client_termname Terminal name of client
2228 client_tty Pseudo terminal of client
2229 client_utf8 1 if client supports UTF-8
2230 client_width Width of client
2231 client_written Bytes written to client
2232 command Name of command in use, if any
2233 command_list_alias Command alias if listing commands
2234 command_list_name Command name if listing commands
2235 command_list_usage Command usage if listing commands
2236 copy_cursor_line Line the cursor is on in copy mode
2237 copy_cursor_word Word under cursor in copy mode
2238 copy_cursor_x Cursor X position in copy mode
2239 copy_cursor_y Cursor Y position in copy mode
2240 cursor_character Character at cursor in pane
2241 cursor_flag Pane cursor flag
2242 cursor_x Cursor X position in pane
2243 cursor_y Cursor Y position in pane
2244 history_bytes Number of bytes in window history
2245 history_limit Maximum window history lines
2246 history_size Size of history in lines
2247 hook Name of running hook, if any
2248 hook_pane ID of pane where hook was run, if any
2249 hook_session ID of session where hook was run, if any
2250 hook_session_name Name of session where hook was run, if
2251 any
2252 hook_window ID of window where hook was run, if any
2253 hook_window_name Name of window where hook was run, if any
2254 host #H Hostname of local host
2255 host_short #h Hostname of local host (no domain name)
2256 insert_flag Pane insert flag
2257 keypad_cursor_flag Pane keypad cursor flag
2258 keypad_flag Pane keypad flag
2259 line Line number in the list
2260 mouse_all_flag Pane mouse all flag
2261 mouse_any_flag Pane mouse any flag
2262 mouse_button_flag Pane mouse button flag
2263 mouse_line Line under mouse, if any
2264 mouse_sgr_flag Pane mouse SGR flag
2265 mouse_standard_flag Pane mouse standard flag
2266 mouse_utf8_flag Pane mouse UTF-8 flag
2267 mouse_word Word under mouse, if any
2268 mouse_x Mouse X position, if any
2269 mouse_y Mouse Y position, if any
2270 origin_flag Pane origin flag
2271 pane_active 1 if active pane
2272 pane_at_bottom 1 if pane is at the bottom of window
2273 pane_at_left 1 if pane is at the left of window
2274 pane_at_right 1 if pane is at the right of window
2275 pane_at_top 1 if pane is at the top of window
2276 pane_bottom Bottom of pane
2277 pane_current_command Current command if available
2278 pane_current_path Current path if available
2279 pane_dead 1 if pane is dead
2280 pane_dead_status Exit status of process in dead pane
2281 pane_format 1 if format is for a pane
2282 pane_height Height of pane
2283 pane_id #D Unique pane ID
2284 pane_in_mode 1 if pane is in a mode
2285 pane_index #P Index of pane
2286 pane_input_off 1 if input to pane is disabled
2287 pane_left Left of pane
2288 pane_marked 1 if this is the marked pane
2289 pane_marked_set 1 if a marked pane is set
2290 pane_mode Name of pane mode, if any
2291 pane_path #T Path of pane (can be set by application)
2292 pane_pid PID of first process in pane
2293 pane_pipe 1 if pane is being piped
2294 pane_right Right of pane
2295 pane_search_string Last search string in copy mode
2296 pane_start_command Command pane started with
2297 pane_synchronized 1 if pane is synchronized
2298 pane_tabs Pane tab positions
2299 pane_title #T Title of pane (can be set by application)
2300 pane_top Top of pane
2301 pane_tty Pseudo terminal of pane
2302 pane_width Width of pane
2303 pid Server PID
2304 rectangle_toggle 1 if rectangle selection is activated
2305 scroll_position Scroll position in copy mode
2306 scroll_region_lower Bottom of scroll region in pane
2307 scroll_region_upper Top of scroll region in pane
2308 selection_active 1 if selection started and changes with
2309 the cursor in copy mode
2310 selection_end_x X position of the end of the selection
2311 selection_end_y Y position of the end of the selection
2312 selection_present 1 if selection started in copy mode
2313 selection_start_x X position of the start of the selection
2314 selection_start_y Y position of the start of the selection
2315 session_activity Time of session last activity
2316 session_alerts List of window indexes with alerts
2317 session_attached Number of clients session is attached to
2318 session_attached_list List of clients session is attached to
2319 session_created Time session created
2320 session_format 1 if format is for a session
2321 session_group Name of session group
2322 session_group_attached Number of clients sessions in group are
2323 attached to
2324 session_group_attached_list List of clients sessions in group are
2325 attached to
2326 session_group_list List of sessions in group
2327 session_group_many_attached 1 if multiple clients attached to
2328 sessions in group
2329 session_group_size Size of session group
2330 session_grouped 1 if session in a group
2331 session_id Unique session ID
2332 session_last_attached Time session last attached
2333 session_many_attached 1 if multiple clients attached
2334 session_name #S Name of session
2335 session_stack Window indexes in most recent order
2336 session_windows Number of windows in session
2337 socket_path Server socket path
2338 start_time Server start time
2339 version Server version
2340 window_active 1 if window active
2341 window_active_clients Number of clients viewing this window
2342 window_active_clients_list List of clients viewing this window
2343 window_active_sessions Number of sessions on which this window
2344 is active
2345 window_active_sessions_list List of sessions on which this window is
2346 active
2347 window_activity Time of window last activity
2348 window_activity_flag 1 if window has activity
2349 window_bell_flag 1 if window has bell
2350 window_bigger 1 if window is larger than client
2351 window_cell_height Height of each cell in pixels
2352 window_cell_width Width of each cell in pixels
2353 window_end_flag 1 if window has the highest index
2354 window_flags #F Window flags
2355 window_format 1 if format is for a window
2356 window_height Height of window
2357 window_id Unique window ID
2358 window_index #I Index of window
2359 window_last_flag 1 if window is the last used
2360 window_layout Window layout description, ignoring
2361 zoomed window panes
2362 window_linked 1 if window is linked across sessions
2363 window_linked_sessions Number of sessions this window is linked
2364 to
2365 window_linked_sessions_list List of sessions this window is linked to
2366 window_marked_flag 1 if window contains the marked pane
2367 window_name #W Name of window
2368 window_offset_x X offset into window if larger than
2369 client
2370 window_offset_y Y offset into window if larger than
2371 client
2372 window_panes Number of panes in window
2373 window_silence_flag 1 if window has silence alert
2374 window_stack_index Index in session most recent stack
2375 window_start_flag 1 if window has the lowest index
2376 window_visible_layout Window layout description, respecting
2377 zoomed window panes
2378 window_width Width of window
2379 window_zoomed_flag 1 if window is zoomed
2380 wrap_flag Pane wrap flag
2381
2383 tmux offers various options to specify the colour and attributes of
2384 aspects of the interface, for example status-style for the status line.
2385 In addition, embedded styles may be specified in format options, such as
2386 status-left, by enclosing them in ‘#[’ and ‘]’.
2387 A style may be the single term ‘default’ to specify the default style
2389 (which may come from an option, for example status-style in the status
2390 line) or a space or comma separated list of the following:
2391 fg=colour
2393 Set the foreground colour. The colour is one of: black, red,
2394 green, yellow, blue, magenta, cyan, white; if supported the
2395 bright variants brightred, brightgreen, brightyellow; colour0 to
2396 colour255 from the 256-colour set; default for the default
2397 colour; terminal for the terminal default colour; or a hexadeci‐
2398 mal RGB string such as ‘#ffffff’.
2399 bg=colour
2401 Set the background colour.
2402 none Set no attributes (turn off any active attributes).
2404 bright (or bold), dim, underscore, blink, reverse, hidden, italics,
2406 overline, strikethrough, double-underscore, curly-underscore,
2407 dotted-underscore, dashed-underscore
2408 Set an attribute. Any of the attributes may be prefixed with
2409 ‘no’ to unset.
2410 align=left (or noalign), align=centre, align=right
2412 Align text to the left, centre or right of the available space if
2413 appropriate.
2414 fill=colour
2416 Fill the available space with a background colour if appropriate.
2417 list=on, list=focus, list=left-marker, list=right-marker, nolist
2419 Mark the position of the various window list components in the
2420 status-format option: list=on marks the start of the list;
2421 list=focus is the part of the list that should be kept in focus
2422 if the entire list won't fit in the available space (typically
2423 the current window); list=left-marker and list=right-marker mark
2424 the text to be used to mark that text has been trimmed from the
2425 left or right of the list if there is not enough space.
2426 push-default, pop-default
2428 Store the current colours and attributes as the default or reset
2429 to the previous default. A push-default affects any subsequent
2430 use of the default term until a pop-default. Only one default
2431 may be pushed (each push-default replaces the previous saved
2432 default).
2433 range=left, range=right, range=window|X, norange
2435 Mark a range in the status-format option. range=left and
2436 range=right are the text used for the ‘StatusLeft’ and
2437 ‘StatusRight’ mouse keys. range=window|X is the range for a win‐
2438 dow passed to the ‘Status’ mouse key, where ‘X’ is a window
2439 index.
2440 Examples are:
2442 fg=yellow bold underscore blink
2444 bg=black,fg=default,noreverse
2445
2447 tmux distinguishes between names and titles. Windows and sessions have
2448 names, which may be used to specify them in targets and are displayed in
2449 the status line and various lists: the name is the tmux identifier for a
2450 window or session. Only panes have titles. A pane's title is typically
2451 set by the program running inside the pane using an escape sequence (like
2452 it would set the xterm(1) window title in X(7)). Windows themselves do
2453 not have titles - a window's title is the title of its active pane. tmux
2454 itself may set the title of the terminal in which the client is running,
2455 see the set-titles option.
2456 A session's name is set with the new-session and rename-session commands.
2458 A window's name is set with one of:
2459 1. A command argument (such as -n for new-window or new-session).
2461 2. An escape sequence (if the allow-rename option is turned on):
2463 $ printf '\033kWINDOW_NAME\033\\'
2465 3. Automatic renaming, which sets the name to the active command in
2467 the window's active pane. See the automatic-rename option.
2468 When a pane is first created, its title is the hostname. A pane's title
2470 can be set via the title setting escape sequence, for example:
2471 $ printf '\033]2;My Title\033\\'
2473 It can also be modified with the select-pane -T command.
2475
2477 When the server is started, tmux copies the environment into the global
2478 environment; in addition, each session has a session environment. When a
2479 window is created, the session and global environments are merged. If a
2480 variable exists in both, the value from the session environment is used.
2481 The result is the initial environment passed to the new process.
2482 The update-environment session option may be used to update the session
2484 environment from the client when a new session is created or an old reat‐
2485 tached. tmux also initialises the TMUX variable with some internal
2486 information to allow commands to be executed from inside, and the TERM
2487 variable with the correct terminal setting of ‘screen’.
2488 Commands to alter and view the environment are:
2490 set-environment [-gru] [-t target-session] name [value]
2492 (alias: setenv)
2493 Set or unset an environment variable. If -g is used, the change
2494 is made in the global environment; otherwise, it is applied to
2495 the session environment for target-session. The -u flag unsets a
2496 variable. -r indicates the variable is to be removed from the
2497 environment before starting a new process.
2498 show-environment [-gs] [-t target-session] [variable]
2500 (alias: showenv)
2501 Display the environment for target-session or the global environ‐
2502 ment with -g. If variable is omitted, all variables are shown.
2503 Variables removed from the environment are prefixed with ‘-’. If
2504 -s is used, the output is formatted as a set of Bourne shell com‐
2505 mands.
2506
2508 tmux includes an optional status line which is displayed in the bottom
2509 line of each terminal.
2510 By default, the status line is enabled and one line in height (it may be
2512 disabled or made multiple lines with the status session option) and con‐
2513 tains, from left-to-right: the name of the current session in square
2514 brackets; the window list; the title of the active pane in double quotes;
2515 and the time and date.
2516 Each line of the status line is configured with the status-format option.
2518 The default is made of three parts: configurable left and right sections
2519 (which may contain dynamic content such as the time or output from a
2520 shell command, see the status-left, status-left-length, status-right, and
2521 status-right-length options below), and a central window list. By
2522 default, the window list shows the index, name and (if any) flag of the
2523 windows present in the current session in ascending numerical order. It
2524 may be customised with the window-status-format and
2525 window-status-current-format options. The flag is one of the following
2526 symbols appended to the window name:
2527 Symbol Meaning
2529 * Denotes the current window.
2530 - Marks the last window (previously selected).
2531 # Window activity is monitored and activity has been
2532 detected.
2533 ! Window bells are monitored and a bell has occurred in the
2534 window.
2535 ~ The window has been silent for the monitor-silence
2536 interval.
2537 M The window contains the marked pane.
2538 Z The window's active pane is zoomed.
2539 The # symbol relates to the monitor-activity window option. The window
2541 name is printed in inverted colours if an alert (bell, activity or
2542 silence) is present.
2543 The colour and attributes of the status line may be configured, the
2545 entire status line using the status-style session option and individual
2546 windows using the window-status-style window option.
2547 The status line is automatically refreshed at interval if it has changed,
2549 the interval may be controlled with the status-interval session option.
2550 Commands related to the status line are as follows:
2552 command-prompt [-1ikN] [-I inputs] [-p prompts] [-t target-client]
2554 [template]
2555 Open the command prompt in a client. This may be used from
2556 inside tmux to execute commands interactively.
2557 If template is specified, it is used as the command. If present,
2559 -I is a comma-separated list of the initial text for each prompt.
2560 If -p is given, prompts is a comma-separated list of prompts
2561 which are displayed in order; otherwise a single prompt is dis‐
2562 played, constructed from template if it is present, or ‘:’ if
2563 not.
2564 Before the command is executed, the first occurrence of the
2566 string ‘%%’ and all occurrences of ‘%1’ are replaced by the
2567 response to the first prompt, all ‘%2’ are replaced with the
2568 response to the second prompt, and so on for further prompts. Up
2569 to nine prompt responses may be replaced (‘%1’ to ‘%9’). ‘%%%’
2570 is like ‘%%’ but any quotation marks are escaped.
2571 -1 makes the prompt only accept one key press, in this case the
2573 resulting input is a single character. -k is like -1 but the key
2574 press is translated to a key name. -N makes the prompt only
2575 accept numeric key presses. -i executes the command every time
2576 the prompt input changes instead of when the user exits the com‐
2577 mand prompt.
2578 The following keys have a special meaning in the command prompt,
2580 depending on the value of the status-keys option:
2581 Function vi emacs
2583 Cancel command prompt Escape Escape
2584 Delete from cursor to start of word C-w
2585 Delete entire command d C-u
2586 Delete from cursor to end D C-k
2587 Execute command Enter Enter
2588 Get next command from history Down
2589 Get previous command from history Up
2590 Insert top paste buffer p C-y
2591 Look for completions Tab Tab
2592 Move cursor left h Left
2593 Move cursor right l Right
2594 Move cursor to end $ C-e
2595 Move cursor to next word w M-f
2596 Move cursor to previous word b M-b
2597 Move cursor to start 0 C-a
2598 Transpose characters C-t
2599 confirm-before [-p prompt] [-t target-client] command
2601 (alias: confirm)
2602 Ask for confirmation before executing command. If -p is given,
2603 prompt is the prompt to display; otherwise a prompt is con‐
2604 structed from command. It may contain the special character
2605 sequences supported by the status-left option.
2606 This command works only from inside tmux.
2608 display-menu [-c target-client] [-t target-pane] [-T title] [-x position]
2610 [-y position] name key command ...
2611 (alias: menu)
2612 Display a menu on target-client. target-pane gives the target
2613 for any commands run from the menu.
2614 A menu is passed as a series of arguments: first the menu item
2616 name, second the key shortcut (or empty for none) and third the
2617 command to run when the menu item is chosen. The name and com‐
2618 mand are formats, see the FORMATS and STYLES sections. If the
2619 name begins with a hyphen (-), then the item is disabled (shown
2620 dim) and may not be chosen. The name may be empty for a separa‐
2621 tor line, in which case both the key and command should be omit‐
2622 ted.
2623 -T is a format for the menu title (see FORMATS).
2625 -x and -y give the position of the menu. Both may be a row or
2627 column number, or one of the following special values:
2628 Value Flag Meaning
2630 R -x The right side of the terminal
2631 P Both The bottom left of the pane
2632 M Both The mouse position
2633 W -x The window position on the status line
2634 S -y The line above or below the status line
2635 Each menu consists of items followed by a key shortcut shown in
2637 brackets. If the menu is too large to fit on the terminal, it is
2638 not displayed. Pressing the key shortcut chooses the correspond‐
2639 ing item. If the mouse is enabled and the menu is opened from a
2640 mouse key binding, releasing the mouse button with an item
2641 selected will choose that item. The following keys are also
2642 available:
2643 Key Function
2645 Enter Choose selected item
2646 Up Select previous item
2647 Down Select next item
2648 q Exit menu
2649 display-message [-aIpv] [-c target-client] [-t target-pane] [message]
2651 (alias: display)
2652 Display a message. If -p is given, the output is printed to std‐
2653 out, otherwise it is displayed in the target-client status line.
2654 The format of message is described in the FORMATS section; infor‐
2655 mation is taken from target-pane if -t is given, otherwise the
2656 active pane.
2657 -v prints verbose logging as the format is parsed and -a lists
2659 the format variables and their values.
2660 -I forwards any input read from stdin to the empty pane given by
2662 target-pane.
2663
2665 tmux maintains a set of named paste buffers. Each buffer may be either
2666 explicitly or automatically named. Explicitly named buffers are named
2667 when created with the set-buffer or load-buffer commands, or by renaming
2668 an automatically named buffer with set-buffer -n. Automatically named
2669 buffers are given a name such as ‘buffer0001’, ‘buffer0002’ and so on.
2670 When the buffer-limit option is reached, the oldest automatically named
2671 buffer is deleted. Explicitly named buffers are not subject to
2672 buffer-limit and may be deleted with the delete-buffer command.
2673 Buffers may be added using copy-mode or the set-buffer and load-buffer
2675 commands, and pasted into a window using the paste-buffer command. If a
2676 buffer command is used and no buffer is specified, the most recently
2677 added automatically named buffer is assumed.
2678 A configurable history buffer is also maintained for each window. By
2680 default, up to 2000 lines are kept; this can be altered with the
2681 history-limit option (see the set-option command above).
2682 The buffer commands are as follows:
2684 choose-buffer [-NZr] [-F format] [-f filter] [-O sort-order] [-t
2686 target-pane] [template]
2687 Put a pane into buffer mode, where a buffer may be chosen inter‐
2688 actively from a list. -Z zooms the pane. The following keys may
2689 be used in buffer mode:
2690 Key Function
2692 Enter Paste selected buffer
2693 Up Select previous buffer
2694 Down Select next buffer
2695 C-s Search by name or content
2696 n Repeat last search
2697 t Toggle if buffer is tagged
2698 T Tag no buffers
2699 C-t Tag all buffers
2700 p Paste selected buffer
2701 P Paste tagged buffers
2702 d Delete selected buffer
2703 D Delete tagged buffers
2704 f Enter a format to filter items
2705 O Change sort field
2706 r Reverse sort order
2707 v Toggle preview
2708 q Exit mode
2709 After a buffer is chosen, ‘%%’ is replaced by the buffer name in
2711 template and the result executed as a command. If template is
2712 not given, "paste-buffer -b '%%'" is used.
2713 -O specifies the initial sort field: one of ‘time’, ‘name’ or
2715 ‘size’. -r reverses the sort order. -f specifies an initial
2716 filter: the filter is a format - if it evaluates to zero, the
2717 item in the list is not shown, otherwise it is shown. If a fil‐
2718 ter would lead to an empty list, it is ignored. -F specifies the
2719 format for each item in the list. -N starts without the preview.
2720 This command works only if at least one client is attached.
2721 clear-history [-t target-pane]
2723 (alias: clearhist)
2724 Remove and free the history for the specified pane.
2725 delete-buffer [-b buffer-name]
2727 (alias: deleteb)
2728 Delete the buffer named buffer-name, or the most recently added
2729 automatically named buffer if not specified.
2730 list-buffers [-F format]
2732 (alias: lsb)
2733 List the global buffers. For the meaning of the -F flag, see the
2734 FORMATS section.
2735 load-buffer [-b buffer-name] path
2737 (alias: loadb)
2738 Load the contents of the specified paste buffer from path.
2739 paste-buffer [-dpr] [-b buffer-name] [-s separator] [-t target-pane]
2741 (alias: pasteb)
2742 Insert the contents of a paste buffer into the specified pane.
2743 If not specified, paste into the current one. With -d, also
2744 delete the paste buffer. When output, any linefeed (LF) charac‐
2745 ters in the paste buffer are replaced with a separator, by
2746 default carriage return (CR). A custom separator may be speci‐
2747 fied using the -s flag. The -r flag means to do no replacement
2748 (equivalent to a separator of LF). If -p is specified, paste
2749 bracket control codes are inserted around the buffer if the
2750 application has requested bracketed paste mode.
2751 save-buffer [-a] [-b buffer-name] path
2753 (alias: saveb)
2754 Save the contents of the specified paste buffer to path. The -a
2755 option appends to rather than overwriting the file.
2756 set-buffer [-a] [-b buffer-name] [-n new-buffer-name] data
2758 (alias: setb)
2759 Set the contents of the specified buffer to data. The -a option
2760 appends to rather than overwriting the buffer. The -n option
2761 renames the buffer to new-buffer-name.
2762 show-buffer [-b buffer-name]
2764 (alias: showb)
2765 Display the contents of the specified buffer.
2766
2768 Miscellaneous commands are as follows:
2769 clock-mode [-t target-pane]
2771 Display a large clock.
2772 if-shell [-bF] [-t target-pane] shell-command command [command]
2774 (alias: if)
2775 Execute the first command if shell-command returns success or the
2776 second command otherwise. Before being executed, shell-command
2777 is expanded using the rules specified in the FORMATS section,
2778 including those relevant to target-pane. With -b, shell-command
2779 is run in the background.
2780 If -F is given, shell-command is not executed but considered suc‐
2782 cess if neither empty nor zero (after formats are expanded).
2783 lock-server
2785 (alias: lock)
2786 Lock each client individually by running the command specified by
2787 the lock-command option.
2788 run-shell [-b] [-t target-pane] shell-command
2790 (alias: run)
2791 Execute shell-command in the background without creating a win‐
2792 dow. Before being executed, shell-command is expanded using the
2793 rules specified in the FORMATS section. With -b, the command is
2794 run in the background. After it finishes, any output to stdout
2795 is displayed in copy mode (in the pane specified by -t or the
2796 current pane if omitted). If the command doesn't return success,
2797 the exit status is also displayed.
2798 wait-for [-L | -S | -U] channel
2800 (alias: wait)
2801 When used without options, prevents the client from exiting until
2802 woken using wait-for -S with the same channel. When -L is used,
2803 the channel is locked and any clients that try to lock the same
2804 channel are made to wait until the channel is unlocked with
2805 wait-for -U.
2806
2808 When a tmux client detaches, it prints a message. This may be one of:
2809 [detached (from session ...)]
2811 The client was detached normally.
2812 [detached and SIGHUP]
2814 The client was detached and its parent sent the SIGHUP signal
2815 (for example with detach-client -P).
2816 [lost tty]
2818 The client's tty(4) or pty(4) was unexpectedly destroyed.
2819 [terminated]
2821 The client was killed with SIGTERM.
2822 [exited]
2824 The server exited when it had no sessions.
2825 [server exited]
2827 The server exited when it received SIGTERM.
2828 [server exited unexpectedly]
2830 The server crashed or otherwise exited without telling the client
2831 the reason.
2832
2834 tmux understands some unofficial extensions to terminfo(5):
2835 Cs, Cr Set the cursor colour. The first takes a single string argument
2837 and is used to set the colour; the second takes no arguments and
2838 restores the default cursor colour. If set, a sequence such as
2839 this may be used to change the cursor colour from inside tmux:
2840 $ printf '\033]12;red\033\\'
2842 Smol Enable the overline attribute. The capability is usually SGR 53
2844 and can be added to terminal-overrides as:
2845 Smol=\E[53m
2847 Smulx Set a styled underscore. The single parameter is one of: 0 for
2849 no underscore, 1 for normal underscore, 2 for double underscore,
2850 3 for curly underscore, 4 for dotted underscore and 5 for dashed
2851 underscore. The capability can typically be added to
2852 terminal-overrides as:
2853 Smulx=\E[4::%p1%dm
2855 Setulc Set the underscore colour. The argument is (red * 65536) +
2857 (green * 256) + blue where each is between 0 and 255. The capa‐
2858 bility can typically be added to terminal-overrides as:
2859 Setulc=\E[58::2::%p1%{65536}%/%d::%p1%{256}%/%{255}%&%d::%p1%{255}%&%d%;m
2861 Ss, Se Set or reset the cursor style. If set, a sequence such as this
2863 may be used to change the cursor to an underline:
2864 $ printf '\033[4 q'
2866 If Se is not set, Ss with argument 0 will be used to reset the
2868 cursor style instead.
2869 Tc Indicate that the terminal supports the ‘direct colour’ RGB
2871 escape sequence (for example, \e[38;2;255;255;255m).
2872 If supported, this is used for the initialize colour escape
2874 sequence (which may be enabled by adding the ‘initc’ and ‘ccc’
2875 capabilities to the tmux [22mterminfo(5) entry).
2876 Ms Store the current buffer in the host terminal's selection (clip‐
2878 board). See the set-clipboard option above and the xterm(1) man
2879 page.
2880
2882 tmux offers a textual interface called control mode. This allows appli‐
2883 cations to communicate with tmux using a simple text-only protocol.
2884 In control mode, a client sends tmux commands or command sequences termi‐
2886 nated by newlines on standard input. Each command will produce one block
2887 of output on standard output. An output block consists of a %begin line
2888 followed by the output (which may be empty). The output block ends with
2889 a %end or %error. %begin and matching %end or %error have two arguments:
2890 an integer time (as seconds from epoch) and command number. For example:
2891 %begin 1363006971 2
2893 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
2894 %end 1363006971 2
2895 The refresh-client -C command may be used to set the size of a client in
2897 control mode.
2898 In control mode, tmux outputs notifications. A notification will never
2900 occur inside an output block.
2901 The following notifications are defined:
2903 %client-session-changed client session-id name
2905 The client is now attached to the session with ID session-id,
2906 which is named name.
2907 %exit [reason]
2909 The tmux client is exiting immediately, either because it is not
2910 attached to any session or an error occurred. If present, reason
2911 describes why the client exited.
2912 %layout-change window-id window-layout window-visible-layout window-flags
2914 The layout of a window with ID window-id changed. The new layout
2915 is window-layout. The window's visible layout is
2916 window-visible-layout and the window flags are window-flags.
2917 %output pane-id value
2919 A window pane produced output. value escapes non-printable char‐
2920 acters and backslash as octal \xxx.
2921 %pane-mode-changed pane-id
2923 The pane with ID pane-id has changed mode.
2924 %session-changed session-id name
2926 The client is now attached to the session with ID session-id,
2927 which is named name.
2928 %session-renamed name
2930 The current session was renamed to name.
2931 %session-window-changed session-id window-id
2933 The session with ID session-id changed its active window to the
2934 window with ID window-id.
2935 %sessions-changed
2937 A session was created or destroyed.
2938 %unlinked-window-add window-id
2940 The window with ID window-id was created but is not linked to the
2941 current session.
2942 %window-add window-id
2944 The window with ID window-id was linked to the current session.
2945 %window-close window-id
2947 The window with ID window-id closed.
2948 %window-pane-changed window-id pane-id
2950 The active pane in the window with ID window-id changed to the
2951 pane with ID pane-id.
2952 %window-renamed window-id name
2954 The window with ID window-id was renamed to name.
2955
2957 When tmux is started, it inspects the following environment variables:
2958 EDITOR If the command specified in this variable contains the string
2960 ‘vi’ and VISUAL is unset, use vi-style key bindings. Overrid‐
2961 den by the mode-keys and status-keys options.
2962 HOME The user's login directory. If unset, the passwd(5) database
2964 is consulted.
2965 LC_CTYPE The character encoding locale(1). It is used for two separate
2967 purposes. For output to the terminal, UTF-8 is used if the -u
2968 option is given or if LC_CTYPE contains "UTF-8" or "UTF8".
2969 Otherwise, only ASCII characters are written and non-ASCII
2970 characters are replaced with underscores (‘_’). For input,
2971 tmux always runs with a UTF-8 locale. If en_US.UTF-8 is pro‐
2972 vided by the operating system it is used and LC_CTYPE is
2973 ignored for input. Otherwise, LC_CTYPE tells tmux what the
2974 UTF-8 locale is called on the current system. If the locale
2975 specified by LC_CTYPE is not available or is not a UTF-8
2976 locale, tmux exits with an error message.
2977 LC_TIME The date and time format locale(1). It is used for locale-
2979 dependent strftime(3) format specifiers.
2980 PWD The current working directory to be set in the global environ‐
2982 ment. This may be useful if it contains symbolic links. If
2983 the value of the variable does not match the current working
2984 directory, the variable is ignored and the result of getcwd(3)
2985 is used instead.
2986 SHELL The absolute path to the default shell for new windows. See
2988 the default-shell option for details.
2989 TMUX_TMPDIR
2991 The parent directory of the directory containing the server
2992 sockets. See the -L option for details.
2993 VISUAL If the command specified in this variable contains the string
2995 ‘vi’, use vi-style key bindings. Overridden by the mode-keys
2996 and status-keys options.
2997
2999 ~/.tmux.conf Default tmux configuration file.
3000 /etc/tmux.conf System-wide configuration file.
3001
3003 To create a new tmux session running vi(1):
3004 $ tmux new-session vi
3006 Most commands have a shorter form, known as an alias. For new-session,
3008 this is new:
3009 $ tmux new vi
3011 Alternatively, the shortest unambiguous form of a command is accepted.
3013 If there are several options, they are listed:
3014 $ tmux n
3016 ambiguous command: n, could be: new-session, new-window, next-window
3017 Within an active session, a new window may be created by typing ‘C-b c’
3019 (Ctrl followed by the ‘b’ key followed by the ‘c’ key).
3020 Windows may be navigated with: ‘C-b 0’ (to select window 0), ‘C-b 1’ (to
3022 select window 1), and so on; ‘C-b n’ to select the next window; and ‘C-b
3023 p’ to select the previous window.
3024 A session may be detached using ‘C-b d’ (or by an external event such as
3026 ssh(1) disconnection) and reattached with:
3027 $ tmux attach-session
3029 Typing ‘C-b ?’ lists the current key bindings in the current window; up
3031 and down may be used to navigate the list or ‘q’ to exit from it.
3032 Commands to be run when the tmux server is started may be placed in the
3034 ~/.tmux.conf configuration file. Common examples include:
3035 Changing the default prefix key:
3037 set-option -g prefix C-a
3039 unbind-key C-b
3040 bind-key C-a send-prefix
3041 Turning the status line off, or changing its colour:
3043 set-option -g status off
3045 set-option -g status-style bg=blue
3046 Setting other options, such as the default command, or locking after 30
3048 minutes of inactivity:
3049 set-option -g default-command "exec /bin/ksh"
3051 set-option -g lock-after-time 1800
3052 Creating new key bindings:
3054 bind-key b set-option status
3056 bind-key / command-prompt "split-window 'exec man %%'"
3057 bind-key S command-prompt "new-window -n %1 'ssh %1'"
3058
3060 pty(4)
3061
3063 Nicholas Marriott <nicholas.marriott@gmail.com>
3064BSD April 11, 2021 BSD