1TMUX(1) BSD General Commands Manual TMUX(1)
2
4 tmux — terminal multiplexer
5
7 tmux [-2CDluvV] [-c shell-command] [-f file] [-L socket-name]
8 [-S socket-path] [-T features] [command [flags]]
9
11 tmux is a terminal multiplexer: it enables a number of terminals to be
12 created, accessed, and controlled from a single screen. tmux may be de‐
13 tached from a screen and continue running in the background, then later
14 reattached.
15 When tmux is started, it creates a new session with a single window and
17 displays it on screen. A status line at the bottom of the screen shows
18 information on the current session and is used to enter interactive com‐
19 mands.
20 A session is a single collection of pseudo terminals under the management
22 of tmux. Each session has one or more windows linked to it. A window
23 occupies the entire screen and may be split into rectangular panes, each
24 of which is a separate pseudo terminal (the pty(4) manual page documents
25 the technical details of pseudo terminals). Any number of tmux instances
26 may connect to the same session, and any number of windows may be present
27 in the same session. Once all sessions are killed, tmux exits.
28 Each session is persistent and will survive accidental disconnection
30 (such as ssh(1) connection timeout) or intentional detaching (with the
31 ‘C-b d’ key strokes). tmux may be reattached using:
32 $ tmux attach
34 In tmux, a session is displayed on screen by a client and all sessions
36 are managed by a single server. The server and each client are separate
37 processes which communicate through a socket in /tmp.
38 The options are as follows:
40 -2 Force tmux to assume the terminal supports 256 colours.
42 This is equivalent to -T 256.
43 -C Start in control mode (see the CONTROL MODE section).
45 Given twice (-CC) disables echo.
46 -c shell-command
48 Execute shell-command using the default shell. If neces‐
49 sary, the tmux server will be started to retrieve the
50 default-shell option. This option is for compatibility
51 with sh(1) when tmux is used as a login shell.
52 -D Do not start the tmux server as a daemon. This also turns
54 the exit-empty option off. With -D, command may not be
55 specified.
56 -f file Specify an alternative configuration file. By default,
58 tmux loads the system configuration file from
59 /etc/tmux.conf, if present, then looks for a user configu‐
60 ration file at ~/.tmux.conf,
61 $XDG_CONFIG_HOME/tmux/tmux.conf or
62 ~/.config/tmux/tmux.conf.
63 The configuration file is a set of tmux commands which are
65 executed in sequence when the server is first started.
66 tmux loads configuration files once when the server process
67 has started. The source-file command may be used to load a
68 file later.
69 tmux shows any error messages from commands in configura‐
71 tion files in the first session created, and continues to
72 process the rest of the configuration file.
73 -L socket-name
75 tmux stores the server socket in a directory under
76 TMUX_TMPDIR or /tmp if it is unset. The default socket is
77 named default. This option allows a different socket name
78 to be specified, allowing several independent tmux servers
79 to be run. Unlike -S a full path is not necessary: the
80 sockets are all created in a directory tmux-UID under the
81 directory given by TMUX_TMPDIR or in /tmp. The tmux-UID
82 directory is created by tmux and must not be world read‐
83 able, writable or executable.
84 If the socket is accidentally removed, the SIGUSR1 signal
86 may be sent to the tmux server process to recreate it (note
87 that this will fail if any parent directories are missing).
88 -l Behave as a login shell. This flag currently has no effect
90 and is for compatibility with other shells when using tmux
91 as a login shell.
92 -N Do not start the server even if the command would normally
94 do so (for example new-session or start-server).
95 -S socket-path
97 Specify a full alternative path to the server socket. If
98 -S is specified, the default socket directory is not used
99 and any -L flag is ignored.
100 -u Write UTF-8 output to the terminal even if the first envi‐
102 ronment variable of LC_ALL, LC_CTYPE, or LANG that is set
103 does not contain "UTF-8" or "UTF8". This is equivalent to
104 -T UTF-8.
105 -T features Set terminal features for the client. This is a comma-sep‐
107 arated list of features. See the terminal-features option.
108 -v Request verbose logging. Log messages will be saved into
110 tmux-client-PID.log and tmux-server-PID.log files in the
111 current directory, where PID is the PID of the server or
112 client process. If -v is specified twice, an additional
113 tmux-out-PID.log file is generated with a copy of every‐
114 thing tmux writes to the terminal.
115 The SIGUSR2 signal may be sent to the tmux server process
117 to toggle logging between on (as if -v was given) and off.
118 -V Report the tmux version.
120 command [flags]
122 This specifies one of a set of commands used to control
123 tmux, as described in the following sections. If no com‐
124 mands are specified, the new-session command is assumed.
125
127 tmux may be controlled from an attached client by using a key combination
128 of a prefix key, ‘C-b’ (Ctrl-b) by default, followed by a command key.
129 The default command key bindings are:
131 C-b Send the prefix key (C-b) through to the application.
133 C-o Rotate the panes in the current window forwards.
134 C-z Suspend the tmux client.
135 ! Break the current pane out of the window.
136 " Split the current pane into two, top and bottom.
137 # List all paste buffers.
138 $ Rename the current session.
139 % Split the current pane into two, left and right.
140 & Kill the current window.
141 ' Prompt for a window index to select.
142 ( Switch the attached client to the previous session.
143 ) Switch the attached client to the next session.
144 , Rename the current window.
145 - Delete the most recently copied buffer of text.
146 . Prompt for an index to move the current window.
147 0 to 9 Select windows 0 to 9.
148 : Enter the tmux command prompt.
149 ; Move to the previously active pane.
150 = Choose which buffer to paste interactively from a list.
151 ? List all key bindings.
152 D Choose a client to detach.
153 L Switch the attached client back to the last session.
154 [ Enter copy mode to copy text or view the history.
155 ] Paste the most recently copied buffer of text.
156 c Create a new window.
157 d Detach the current client.
158 f Prompt to search for text in open windows.
159 i Display some information about the current window.
160 l Move to the previously selected window.
161 m Mark the current pane (see select-pane -m).
162 M Clear the marked pane.
163 n Change to the next window.
164 o Select the next pane in the current window.
165 p Change to the previous window.
166 q Briefly display pane indexes.
167 r Force redraw of the attached client.
168 s Select a new session for the attached client interac‐
169 tively.
170 t Show the time.
171 w Choose the current window interactively.
172 x Kill the current pane.
173 z Toggle zoom state of the current pane.
174 { Swap the current pane with the previous pane.
175 } Swap the current pane with the next pane.
176 ~ Show previous messages from tmux, if any.
177 Page Up Enter copy mode and scroll one page up.
178 Up, Down
179 Left, Right
180 Change to the pane above, below, to the left, or to the
181 right of the current pane.
182 M-1 to M-5 Arrange panes in one of the five preset layouts: even-
183 horizontal, even-vertical, main-horizontal, main-verti‐
184 cal, or tiled.
185 Space Arrange the current window in the next preset layout.
186 M-n Move to the next window with a bell or activity marker.
187 M-o Rotate the panes in the current window backwards.
188 M-p Move to the previous window with a bell or activity
189 marker.
190 C-Up, C-Down
191 C-Left, C-Right
192 Resize the current pane in steps of one cell.
193 M-Up, M-Down
194 M-Left, M-Right
195 Resize the current pane in steps of five cells.
196 Key bindings may be changed with the bind-key and unbind-key commands.
198
200 tmux supports a large number of commands which can be used to control its
201 behaviour. Each command is named and can accept zero or more flags and
202 arguments. They may be bound to a key with the bind-key command or run
203 from the shell prompt, a shell script, a configuration file or the com‐
204 mand prompt. For example, the same set-option command run from the shell
205 prompt, from ~/.tmux.conf and bound to a key may look like:
206 $ tmux set-option -g status-style bg=cyan
208 set-option -g status-style bg=cyan
210 bind-key C set-option -g status-style bg=cyan
212 Here, the command name is ‘set-option’, ‘-g’ is a flag and ‘status-style’
214 and ‘bg=cyan’ are arguments.
215 tmux distinguishes between command parsing and execution. In order to
217 execute a command, tmux needs it to be split up into its name and argu‐
218 ments. This is command parsing. If a command is run from the shell, the
219 shell parses it; from inside tmux or from a configuration file, tmux
220 does. Examples of when tmux parses commands are:
221 - in a configuration file;
223 - typed at the command prompt (see command-prompt);
225 - given to bind-key;
227 - passed as arguments to if-shell or confirm-before.
229 To execute commands, each client has a ‘command queue’. A global command
231 queue not attached to any client is used on startup for configuration
232 files like ~/.tmux.conf. Parsed commands added to the queue are executed
233 in order. Some commands, like if-shell and confirm-before, parse their
234 argument to create a new command which is inserted immediately after
235 themselves. This means that arguments can be parsed twice or more - once
236 when the parent command (such as if-shell) is parsed and again when it
237 parses and executes its command. Commands like if-shell, run-shell and
238 display-panes stop execution of subsequent commands on the queue until
239 something happens - if-shell and run-shell until a shell command finishes
240 and display-panes until a key is pressed. For example, the following
241 commands:
242 new-session; new-window
244 if-shell "true" "split-window"
245 kill-session
246 Will execute new-session, new-window, if-shell, the shell command
248 true(1), split-window and kill-session in that order.
249 The COMMANDS section lists the tmux commands and their arguments.
251
253 This section describes the syntax of commands parsed by tmux, for example
254 in a configuration file or at the command prompt. Note that when com‐
255 mands are entered into the shell, they are parsed by the shell - see for
256 example ksh(1) or csh(1).
257 Each command is terminated by a newline or a semicolon (;). Commands
259 separated by semicolons together form a ‘command sequence’ - if a command
260 in the sequence encounters an error, no subsequent commands are executed.
261 It is recommended that a semicolon used as a command separator should be
263 written as an individual token, for example from sh(1):
264 $ tmux neww \; splitw
266 Or:
268 $ tmux neww ';' splitw
270 Or from the tmux command prompt:
272 neww ; splitw
274 However, a trailing semicolon is also interpreted as a command separator,
276 for example in these sh(1) commands:
277 $ tmux neww\\; splitw
279 Or:
281 $ tmux 'neww;' splitw
283 As in these examples, when running tmux from the shell extra care must be
285 taken to properly quote semicolons:
286 1. Semicolons that should be interpreted as a command separator
288 should be escaped according to the shell conventions. For
289 sh(1) this typically means quoted (such as ‘neww ';' splitw’)
290 or escaped (such as ‘neww \\\\; splitw’).
291 2. Individual semicolons or trailing semicolons that should be
293 interpreted as arguments should be escaped twice: once accord‐
294 ing to the shell conventions and a second time for tmux; for
295 example:
296 $ tmux neww 'foo\\;' bar
298 $ tmux neww foo\\\\; bar
299 3. Semicolons that are not individual tokens or trailing another
301 token should only be escaped once according to shell conven‐
302 tions; for example:
303 $ tmux neww 'foo-;-bar'
305 $ tmux neww foo-\\;-bar
306 Comments are marked by the unquoted # character - any remaining text af‐
308 ter a comment is ignored until the end of the line.
309 If the last character of a line is \, the line is joined with the follow‐
311 ing line (the \ and the newline are completely removed). This is called
312 line continuation and applies both inside and outside quoted strings and
313 in comments, but not inside braces.
314 Command arguments may be specified as strings surrounded by single (')
316 quotes, double quotes (") or braces ({}). This is required when the ar‐
317 gument contains any special character. Single and double quoted strings
318 cannot span multiple lines except with line continuation. Braces can
319 span multiple lines.
320 Outside of quotes and inside double quotes, these replacements are per‐
322 formed:
323 - Environment variables preceded by $ are replaced with their
325 value from the global environment (see the GLOBAL AND SESSION
326 ENVIRONMENT section).
327 - A leading ~ or ~user is expanded to the home directory of the
329 current or specified user.
330 - \uXXXX or \uXXXXXXXX is replaced by the Unicode codepoint cor‐
332 responding to the given four or eight digit hexadecimal number.
333 - When preceded (escaped) by a \, the following characters are
335 replaced: \e by the escape character; \r by a carriage return;
336 \n by a newline; and \t by a tab.
337 - \ooo is replaced by a character of the octal value ooo. Three
339 octal digits are required, for example \001. The largest valid
340 character is \377.
341 - Any other characters preceded by \ are replaced by themselves
343 (that is, the \ is removed) and are not treated as having any
344 special meaning - so for example \; will not mark a command se‐
345 quence and \$ will not expand an environment variable.
346 Braces are parsed as a configuration file (so conditions such as ‘%if’
348 are processed) and then converted into a string. They are designed to
349 avoid the need for additional escaping when passing a group of tmux com‐
350 mands as an argument (for example to if-shell). These two examples pro‐
351 duce an identical command - note that no escaping is needed when using
352 {}:
353 if-shell true {
355 display -p 'brace-dollar-foo: }$foo'
356 }
357 if-shell true "display -p 'brace-dollar-foo: }\$foo'"
359 Braces may be enclosed inside braces, for example:
361 bind x if-shell "true" {
363 if-shell "true" {
364 display "true!"
365 }
366 }
367 Environment variables may be set by using the syntax ‘name=value’, for
369 example ‘HOME=/home/user’. Variables set during parsing are added to the
370 global environment. A hidden variable may be set with ‘%hidden’, for ex‐
371 ample:
372 %hidden MYVAR=42
374 Hidden variables are not passed to the environment of processes created
376 by tmux. See the GLOBAL AND SESSION ENVIRONMENT section.
377 Commands may be parsed conditionally by surrounding them with ‘%if’,
379 ‘%elif’, ‘%else’ and ‘%endif’. The argument to ‘%if’ and ‘%elif’ is ex‐
380 panded as a format (see FORMATS) and if it evaluates to false (zero or
381 empty), subsequent text is ignored until the closing ‘%elif’, ‘%else’ or
382 ‘%endif’. For example:
383 %if "#{==:#{host},myhost}"
385 set -g status-style bg=red
386 %elif "#{==:#{host},myotherhost}"
387 set -g status-style bg=green
388 %else
389 set -g status-style bg=blue
390 %endif
391 Will change the status line to red if running on ‘myhost’, green if run‐
393 ning on ‘myotherhost’, or blue if running on another host. Conditionals
394 may be given on one line, for example:
395 %if #{==:#{host},myhost} set -g status-style bg=red %endif
397
399 This section describes the commands supported by tmux. Most commands ac‐
400 cept the optional -t (and sometimes -s) argument with one of
401 target-client, target-session, target-window, or target-pane. These
402 specify the client, session, window or pane which a command should af‐
403 fect.
404 target-client should be the name of the client, typically the pty(4) file
406 to which the client is connected, for example either of /dev/ttyp1 or
407 ttyp1 for the client attached to /dev/ttyp1. If no client is specified,
408 tmux attempts to work out the client currently in use; if that fails, an
409 error is reported. Clients may be listed with the list-clients command.
410 target-session is tried as, in order:
412 1. A session ID prefixed with a $.
414 2. An exact name of a session (as listed by the list-sessions
416 command).
417 3. The start of a session name, for example ‘mysess’ would match
419 a session named ‘mysession’.
420 4. An fnmatch(3) pattern which is matched against the session
422 name.
423 If the session name is prefixed with an ‘=’, only an exact match is ac‐
425 cepted (so ‘=mysess’ will only match exactly ‘mysess’, not ‘mysession’).
426 If a single session is found, it is used as the target session; multiple
428 matches produce an error. If a session is omitted, the current session
429 is used if available; if no current session is available, the most re‐
430 cently used is chosen.
431 target-window (or src-window or dst-window) specifies a window in the
433 form session:window. session follows the same rules as for
434 target-session, and window is looked for in order as:
435 1. A special token, listed below.
437 2. A window index, for example ‘mysession:1’ is window 1 in ses‐
439 sion ‘mysession’.
440 3. A window ID, such as @1.
442 4. An exact window name, such as ‘mysession:mywindow’.
444 5. The start of a window name, such as ‘mysession:mywin’.
446 6. As an fnmatch(3) pattern matched against the window name.
448 Like sessions, a ‘=’ prefix will do an exact match only. An empty window
450 name specifies the next unused index if appropriate (for example the
451 new-window and link-window commands) otherwise the current window in
452 session is chosen.
453 The following special tokens are available to indicate particular win‐
455 dows. Each has a single-character alternative form.
456 Token Meaning
458 {start} ^ The lowest-numbered window
459 {end} $ The highest-numbered window
460 {last} ! The last (previously current) window
461 {next} + The next window by number
462 {previous} - The previous window by number
463 target-pane (or src-pane or dst-pane) may be a pane ID or takes a similar
465 form to target-window but with the optional addition of a period followed
466 by a pane index or pane ID, for example: ‘mysession:mywindow.1’. If the
467 pane index is omitted, the currently active pane in the specified window
468 is used. The following special tokens are available for the pane index:
469 Token Meaning
471 {last} ! The last (previously active) pane
472 {next} + The next pane by number
473 {previous} - The previous pane by number
474 {top} The top pane
475 {bottom} The bottom pane
476 {left} The leftmost pane
477 {right} The rightmost pane
478 {top-left} The top-left pane
479 {top-right} The top-right pane
480 {bottom-left} The bottom-left pane
481 {bottom-right} The bottom-right pane
482 {up-of} The pane above the active pane
483 {down-of} The pane below the active pane
484 {left-of} The pane to the left of the active pane
485 {right-of} The pane to the right of the active pane
486 The tokens ‘+’ and ‘-’ may be followed by an offset, for example:
488 select-window -t:+2
490 In addition, target-session, target-window or target-pane may consist en‐
492 tirely of the token ‘{mouse}’ (alternative form ‘=’) to specify the ses‐
493 sion, window or pane where the most recent mouse event occurred (see the
494 MOUSE SUPPORT section) or ‘{marked}’ (alternative form ‘~’) to specify
495 the marked pane (see select-pane -m).
496 Sessions, window and panes are each numbered with a unique ID; session
498 IDs are prefixed with a ‘$’, windows with a ‘@’, and panes with a ‘%’.
499 These are unique and are unchanged for the life of the session, window or
500 pane in the tmux server. The pane ID is passed to the child process of
501 the pane in the TMUX_PANE environment variable. IDs may be displayed us‐
502 ing the ‘session_id’, ‘window_id’, or ‘pane_id’ formats (see the FORMATS
503 section) and the display-message, list-sessions, list-windows or
504 list-panes commands.
505 shell-command arguments are sh(1) commands. This may be a single argu‐
507 ment passed to the shell, for example:
508 new-window 'vi ~/.tmux.conf'
510 Will run:
512 /bin/sh -c 'vi ~/.tmux.conf'
514 Additionally, the new-window, new-session, split-window, respawn-window
516 and respawn-pane commands allow shell-command to be given as multiple ar‐
517 guments and executed directly (without ‘sh -c’). This can avoid issues
518 with shell quoting. For example:
519 $ tmux new-window vi ~/.tmux.conf
521 Will run vi(1) directly without invoking the shell.
523 command [arguments] refers to a tmux command, either passed with the com‐
525 mand and arguments separately, for example:
526 bind-key F1 set-option status off
528 Or passed as a single string argument in .tmux.conf, for example:
530 bind-key F1 { set-option status off }
532 Example tmux commands include:
534 refresh-client -t/dev/ttyp2
536 rename-session -tfirst newname
538 set-option -wt:0 monitor-activity on
540 new-window ; split-window -d
542 bind-key R source-file ~/.tmux.conf \; \
544 display-message "source-file done"
545 Or from sh(1):
547 $ tmux kill-window -t :1
549 $ tmux new-window \; split-window -d
551 $ tmux new-session -d 'vi ~/.tmux.conf' \; split-window -d \; attach
553
555 The tmux server manages clients, sessions, windows and panes. Clients
556 are attached to sessions to interact with them, either when they are cre‐
557 ated with the new-session command, or later with the attach-session com‐
558 mand. Each session has one or more windows linked into it. Windows may
559 be linked to multiple sessions and are made up of one or more panes, each
560 of which contains a pseudo terminal. Commands for creating, linking and
561 otherwise manipulating windows are covered in the WINDOWS AND PANES sec‐
562 tion.
563 The following commands are available to manage clients and sessions:
565 attach-session [-dErx] [-c working-directory] [-f flags] [-t
567 target-session]
568 (alias: attach)
569 If run from outside tmux, create a new client in the current ter‐
570 minal and attach it to target-session. If used from inside,
571 switch the current client. If -d is specified, any other clients
572 attached to the session are detached. If -x is given, send
573 SIGHUP to the parent process of the client as well as detaching
574 the client, typically causing it to exit. -f sets a comma-sepa‐
575 rated list of client flags. The flags are:
576 active-pane
578 the client has an independent active pane
579 ignore-size
581 the client does not affect the size of other clients
582 no-output
584 the client does not receive pane output in control mode
585 pause-after=seconds
587 output is paused once the pane is seconds behind in con‐
588 trol mode
589 read-only
591 the client is read-only
592 wait-exit
594 wait for an empty line input before exiting in control
595 mode
596 A leading ‘!’ turns a flag off if the client is already attached.
598 -r is an alias for -f read-only,ignore-size. When a client is
599 read-only, only keys bound to the detach-client or switch-client
600 commands have any effect. A client with the active-pane flag al‐
601 lows the active pane to be selected independently of the window's
602 active pane used by clients without the flag. This only affects
603 the cursor position and commands issued from the client; other
604 features such as hooks and styles continue to use the window's
605 active pane.
606 If no server is started, attach-session will attempt to start it;
608 this will fail unless sessions are created in the configuration
609 file.
610 The target-session rules for attach-session are slightly ad‐
612 justed: if tmux needs to select the most recently used session,
613 it will prefer the most recently used unattached session.
614 -c will set the session working directory (used for new windows)
616 to working-directory.
617 If -E is used, the update-environment option will not be applied.
619 detach-client [-aP] [-E shell-command] [-s target-session] [-t
621 target-client]
622 (alias: detach)
623 Detach the current client if bound to a key, the client specified
624 with -t, or all clients currently attached to the session speci‐
625 fied by -s. The -a option kills all but the client given with
626 -t. If -P is given, send SIGHUP to the parent process of the
627 client, typically causing it to exit. With -E, run shell-command
628 to replace the client.
629 has-session [-t target-session]
631 (alias: has)
632 Report an error and exit with 1 if the specified session does not
633 exist. If it does exist, exit with 0.
634 kill-server
636 Kill the tmux server and clients and destroy all sessions.
637 kill-session [-aC] [-t target-session]
639 Destroy the given session, closing any windows linked to it and
640 no other sessions, and detaching all clients attached to it. If
641 -a is given, all sessions but the specified one is killed. The
642 -C flag clears alerts (bell, activity, or silence) in all windows
643 linked to the session.
644 list-clients [-F format] [-t target-session]
646 (alias: lsc)
647 List all clients attached to the server. For the meaning of the
648 -F flag, see the FORMATS section. If target-session is speci‐
649 fied, list only clients connected to that session.
650 list-commands [-F format] [command]
652 (alias: lscm)
653 List the syntax of command or - if omitted - of all commands sup‐
654 ported by tmux.
655 list-sessions [-F format] [-f filter]
657 (alias: ls)
658 List all sessions managed by the server. -F specifies the format
659 of each line and -f a filter. Only sessions for which the filter
660 is true are shown. See the FORMATS section.
661 lock-client [-t target-client]
663 (alias: lockc)
664 Lock target-client, see the lock-server command.
665 lock-session [-t target-session]
667 (alias: locks)
668 Lock all clients attached to target-session.
669 new-session [-AdDEPX] [-c start-directory] [-e environment] [-f flags]
671 [-F format] [-n window-name] [-s session-name] [-t group-name]
672 [-x width] [-y height] [shell-command]
673 (alias: new)
674 Create a new session with name session-name.
675 The new session is attached to the current terminal unless -d is
677 given. window-name and shell-command are the name of and shell
678 command to execute in the initial window. With -d, the initial
679 size comes from the global default-size option; -x and -y can be
680 used to specify a different size. ‘-’ uses the size of the cur‐
681 rent client if any. If -x or -y is given, the default-size op‐
682 tion is set for the session. -f sets a comma-separated list of
683 client flags (see attach-session).
684 If run from a terminal, any termios(4) special characters are
686 saved and used for new windows in the new session.
687 The -A flag makes new-session behave like attach-session if
689 session-name already exists; in this case, -D behaves like -d to
690 attach-session, and -X behaves like -x to attach-session.
691 If -t is given, it specifies a session group. Sessions in the
693 same group share the same set of windows - new windows are linked
694 to all sessions in the group and any windows closed removed from
695 all sessions. The current and previous window and any session
696 options remain independent and any session in a group may be
697 killed without affecting the others. The group-name argument may
698 be:
699 1. the name of an existing group, in which case the new ses‐
701 sion is added to that group;
702 2. the name of an existing session - the new session is
704 added to the same group as that session, creating a new
705 group if necessary;
706 3. the name for a new group containing only the new session.
708 -n and shell-command are invalid if -t is used.
710 The -P option prints information about the new session after it
712 has been created. By default, it uses the format
713 ‘#{session_name}:’ but a different format may be specified with
714 -F.
715 If -E is used, the update-environment option will not be applied.
717 -e takes the form ‘VARIABLE=value’ and sets an environment vari‐
718 able for the newly created session; it may be specified multiple
719 times.
720 refresh-client [-cDLRSU] [-A pane:state] [-B name:what:format] [-C size]
722 [-f flags] [-l [target-pane]] [-t target-client] [adjustment]
723 (alias: refresh)
724 Refresh the current client if bound to a key, or a single client
725 if one is given with -t. If -S is specified, only update the
726 client's status line.
727 The -U, -D, -L -R, and -c flags allow the visible portion of a
729 window which is larger than the client to be changed. -U moves
730 the visible part up by adjustment rows and -D down, -L left by
731 adjustment columns and -R right. -c returns to tracking the cur‐
732 sor automatically. If adjustment is omitted, 1 is used. Note
733 that the visible position is a property of the client not of the
734 window, changing the current window in the attached session will
735 reset it.
736 -C sets the width and height of a control mode client or of a
738 window for a control mode client, size must be one of
739 ‘widthxheight’ or ‘window ID:widthxheight’, for example ‘80x24’
740 or ‘@0:80x24’. -A allows a control mode client to trigger ac‐
741 tions on a pane. The argument is a pane ID (with leading ‘%’), a
742 colon, then one of ‘on’, ‘off’, ‘continue’ or ‘pause’. If ‘off’,
743 tmux will not send output from the pane to the client and if all
744 clients have turned the pane off, will stop reading from the
745 pane. If ‘continue’, tmux will return to sending output to the
746 pane if it was paused (manually or with the pause-after flag).
747 If ‘pause’, tmux will pause the pane. -A may be given multiple
748 times for different panes.
749 -B sets a subscription to a format for a control mode client.
751 The argument is split into three items by colons: name is a name
752 for the subscription; what is a type of item to subscribe to;
753 format is the format. After a subscription is added, changes to
754 the format are reported with the %subscription-changed notifica‐
755 tion, at most once a second. If only the name is given, the sub‐
756 scription is removed. what may be empty to check the format only
757 for the attached session, or one of: a pane ID such as ‘%0’; ‘%*’
758 for all panes in the attached session; a window ID such as ‘@0’;
759 or ‘@*’ for all windows in the attached session.
760 -f sets a comma-separated list of client flags, see
762 attach-session.
763 -l requests the clipboard from the client using the xterm(1) es‐
765 cape sequence. If Ar target-pane is given, the clipboard is sent
766 (in encoded form), otherwise it is stored in a new paste buffer.
767 -L, -R, -U and -D move the visible portion of the window left,
769 right, up or down by adjustment, if the window is larger than the
770 client. -c resets so that the position follows the cursor. See
771 the window-size option.
772 rename-session [-t target-session] new-name
774 (alias: rename)
775 Rename the session to new-name.
776 server-access [-adlrw] [user]
778 Change the access or read/write permission of user. The user
779 running the tmux server (its owner) and the root user cannot be
780 changed and are always permitted access.
781 -a and -d are used to give or revoke access for the specified
783 user. If the user is already attached, the -d flag causes their
784 clients to be detached.
785 -r and -w change the permissions for user: -r makes their clients
787 read-only and -w writable. -l lists current access permissions.
788 By default, the access list is empty and tmux creates sockets
790 with file system permissions preventing access by any user other
791 than the owner (and root). These permissions must be changed
792 manually. Great care should be taken not to allow access to un‐
793 trusted users even read-only.
794 show-messages [-JT] [-t target-client]
796 (alias: showmsgs)
797 Show server messages or information. Messages are stored, up to
798 a maximum of the limit set by the message-limit server option.
799 -J and -T show debugging information about jobs and terminals.
800 source-file [-Fnqv] path ...
802 (alias: source)
803 Execute commands from one or more files specified by path (which
804 may be glob(7) patterns). If -F is present, then path is ex‐
805 panded as a format. If -q is given, no error will be returned if
806 path does not exist. With -n, the file is parsed but no commands
807 are executed. -v shows the parsed commands and line numbers if
808 possible.
809 start-server
811 (alias: start)
812 Start the tmux server, if not already running, without creating
813 any sessions.
814 Note that as by default the tmux server will exit with no ses‐
816 sions, this is only useful if a session is created in
817 ~/.tmux.conf, exit-empty is turned off, or another command is run
818 as part of the same command sequence. For example:
819 $ tmux start \; show -g
821 suspend-client [-t target-client]
823 (alias: suspendc)
824 Suspend a client by sending SIGTSTP (tty stop).
825 switch-client [-ElnprZ] [-c target-client] [-t target-session] [-T
827 key-table]
828 (alias: switchc)
829 Switch the current session for client target-client to
830 target-session. As a special case, -t may refer to a pane (a
831 target that contains ‘:’, ‘.’ or ‘%’), to change session, window
832 and pane. In that case, -Z keeps the window zoomed if it was
833 zoomed. If -l, -n or -p is used, the client is moved to the
834 last, next or previous session respectively. -r toggles the
835 client read-only and ignore-size flags (see the attach-session
836 command).
837 If -E is used, update-environment option will not be applied.
839 -T sets the client's key table; the next key from the client will
841 be interpreted from key-table. This may be used to configure
842 multiple prefix keys, or to bind commands to sequences of keys.
843 For example, to make typing ‘abc’ run the list-keys command:
844 bind-key -Ttable2 c list-keys
846 bind-key -Ttable1 b switch-client -Ttable2
847 bind-key -Troot a switch-client -Ttable1
848
850 Each window displayed by tmux may be split into one or more panes; each
851 pane takes up a certain area of the display and is a separate terminal.
852 A window may be split into panes using the split-window command. Windows
853 may be split horizontally (with the -h flag) or vertically. Panes may be
854 resized with the resize-pane command (bound to ‘C-Up’, ‘C-Down’ ‘C-Left’
855 and ‘C-Right’ by default), the current pane may be changed with the
856 select-pane command and the rotate-window and swap-pane commands may be
857 used to swap panes without changing their position. Panes are numbered
858 beginning from zero in the order they are created.
859 By default, a tmux pane permits direct access to the terminal contained
861 in the pane. A pane may also be put into one of several modes:
862 - Copy mode, which permits a section of a window or its history
864 to be copied to a paste buffer for later insertion into another
865 window. This mode is entered with the copy-mode command, bound
866 to ‘[’ by default. Copied text can be pasted with the
867 paste-buffer command, bound to ‘]’.
868 - View mode, which is like copy mode but is entered when a com‐
870 mand that produces output, such as list-keys, is executed from
871 a key binding.
872 - Choose mode, which allows an item to be chosen from a list.
874 This may be a client, a session or window or pane, or a buffer.
875 This mode is entered with the choose-buffer, choose-client and
876 choose-tree commands.
877 In copy mode an indicator is displayed in the top-right corner of the
879 pane with the current position and the number of lines in the history.
880 Commands are sent to copy mode using the -X flag to the send-keys com‐
882 mand. When a key is pressed, copy mode automatically uses one of two key
883 tables, depending on the mode-keys option: copy-mode for emacs, or
884 copy-mode-vi for vi. Key tables may be viewed with the list-keys com‐
885 mand.
886 The following commands are supported in copy mode:
888 Command vi emacs
890 append-selection
891 append-selection-and-cancel A
892 back-to-indentation ^ M-m
893 begin-selection Space C-Space
894 bottom-line L
895 cancel q Escape
896 clear-selection Escape C-g
897 copy-end-of-line [<prefix>]
898 copy-end-of-line-and-cancel [<prefix>]
899 copy-pipe-end-of-line [<command>] [<prefix>]
900 copy-pipe-end-of-line-and-cancel [<command>]
901 [<prefix>] D C-k
902 copy-line [<prefix>]
903 copy-line-and-cancel [<prefix>]
904 copy-pipe-line [<command>] [<prefix>]
905 copy-pipe-line-and-cancel [<command>]
906 [<prefix>]
907 copy-pipe [<command>] [<prefix>]
908 copy-pipe-no-clear [<command>] [<prefix>]
909 copy-pipe-and-cancel [<command>] [<prefix>]
910 copy-selection [<prefix>]
911 copy-selection-no-clear [<prefix>]
912 copy-selection-and-cancel [<prefix>] Enter M-w
913 cursor-down j Down
914 cursor-down-and-cancel
915 cursor-left h Left
916 cursor-right l Right
917 cursor-up k Up
918 end-of-line $ C-e
919 goto-line <line> : g
920 halfpage-down C-d M-Down
921 halfpage-down-and-cancel
922 halfpage-up C-u M-Up
923 history-bottom G M->
924 history-top g M-<
925 jump-again ; ;
926 jump-backward <to> F F
927 jump-forward <to> f f
928 jump-reverse , ,
929 jump-to-backward <to> T
930 jump-to-forward <to> t
931 jump-to-mark M-x M-x
932 middle-line M M-r
933 next-matching-bracket % M-C-f
934 next-paragraph } M-}
935 next-space W
936 next-space-end E
937 next-word w
938 next-word-end e M-f
939 other-end o
940 page-down C-f PageDown
941 page-down-and-cancel
942 page-up C-b PageUp
943 pipe [<command>] [<prefix>]
944 pipe-no-clear [<command>] [<prefix>]
945 pipe-and-cancel [<command>] [<prefix>]
946 previous-matching-bracket M-C-b
947 previous-paragraph { M-{
948 previous-space B
949 previous-word b M-b
950 rectangle-on
951 rectangle-off
952 rectangle-toggle v R
953 refresh-from-pane r r
954 scroll-down C-e C-Down
955 scroll-down-and-cancel
956 scroll-up C-y C-Up
957 search-again n n
958 search-backward <for> ?
959 search-backward-incremental <for> C-r
960 search-backward-text <for>
961 search-forward <for> /
962 search-forward-incremental <for> C-s
963 search-forward-text <for>
964 search-reverse N N
965 select-line V
966 select-word
967 set-mark X X
968 start-of-line 0 C-a
969 stop-selection
970 toggle-position P P
971 top-line H M-R
972 The search commands come in several varieties: ‘search-forward’ and
974 ‘search-backward’ search for a regular expression; the ‘-text’ variants
975 search for a plain text string rather than a regular expression;
976 ‘-incremental’ perform an incremental search and expect to be used with
977 the -i flag to the command-prompt command. ‘search-again’ repeats the
978 last search and ‘search-reverse’ does the same but reverses the direction
979 (forward becomes backward and backward becomes forward).
980 Copy commands may take an optional buffer prefix argument which is used
982 to generate the buffer name (the default is ‘buffer’ so buffers are named
983 ‘buffer0’, ‘buffer1’ and so on). Pipe commands take a command argument
984 which is the command to which the selected text is piped. ‘copy-pipe’
985 variants also copy the selection. The ‘-and-cancel’ variants of some
986 commands exit copy mode after they have completed (for copy commands) or
987 when the cursor reaches the bottom (for scrolling commands). ‘-no-clear’
988 variants do not clear the selection.
989 The next and previous word keys skip over whitespace and treat consecu‐
991 tive runs of either word separators or other letters as words. Word sep‐
992 arators can be customized with the word-separators session option. Next
993 word moves to the start of the next word, next word end to the end of the
994 next word and previous word to the start of the previous word. The three
995 next and previous space keys work similarly but use a space alone as the
996 word separator. Setting word-separators to the empty string makes
997 next/previous word equivalent to next/previous space.
998 The jump commands enable quick movement within a line. For instance,
1000 typing ‘f’ followed by ‘/’ will move the cursor to the next ‘/’ character
1001 on the current line. A ‘;’ will then jump to the next occurrence.
1002 Commands in copy mode may be prefaced by an optional repeat count. With
1004 vi key bindings, a prefix is entered using the number keys; with emacs,
1005 the Alt (meta) key and a number begins prefix entry.
1006 The synopsis for the copy-mode command is:
1008 copy-mode [-eHMqu] [-s src-pane] [-t target-pane]
1010 Enter copy mode. The -u option scrolls one page up. -M begins a
1011 mouse drag (only valid if bound to a mouse key binding, see MOUSE
1012 SUPPORT). -H hides the position indicator in the top right. -q
1013 cancels copy mode and any other modes. -s copies from src-pane
1014 instead of target-pane.
1015 -e specifies that scrolling to the bottom of the history (to the
1017 visible screen) should exit copy mode. While in copy mode,
1018 pressing a key other than those used for scrolling will disable
1019 this behaviour. This is intended to allow fast scrolling through
1020 a pane's history, for example with:
1021 bind PageUp copy-mode -eu
1023 A number of preset arrangements of panes are available, these are called
1025 layouts. These may be selected with the select-layout command or cycled
1026 with next-layout (bound to ‘Space’ by default); once a layout is chosen,
1027 panes within it may be moved and resized as normal.
1028 The following layouts are supported:
1030 even-horizontal
1032 Panes are spread out evenly from left to right across the window.
1033 even-vertical
1035 Panes are spread evenly from top to bottom.
1036 main-horizontal
1038 A large (main) pane is shown at the top of the window and the re‐
1039 maining panes are spread from left to right in the leftover space
1040 at the bottom. Use the main-pane-height window option to specify
1041 the height of the top pane.
1042 main-vertical
1044 Similar to main-horizontal but the large pane is placed on the
1045 left and the others spread from top to bottom along the right.
1046 See the main-pane-width window option.
1047 tiled Panes are spread out as evenly as possible over the window in
1049 both rows and columns.
1050 In addition, select-layout may be used to apply a previously used layout
1052 - the list-windows command displays the layout of each window in a form
1053 suitable for use with select-layout. For example:
1054 $ tmux list-windows
1056 0: ksh [159x48]
1057 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1058 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1059 tmux automatically adjusts the size of the layout for the current window
1061 size. Note that a layout cannot be applied to a window with more panes
1062 than that from which the layout was originally defined.
1063 Commands related to windows and panes are as follows:
1065 break-pane [-abdP] [-F format] [-n window-name] [-s src-pane] [-t
1067 dst-window]
1068 (alias: breakp)
1069 Break src-pane off from its containing window to make it the only
1070 pane in dst-window. With -a or -b, the window is moved to the
1071 next index after or before (existing windows are moved if neces‐
1072 sary). If -d is given, the new window does not become the cur‐
1073 rent window. The -P option prints information about the new win‐
1074 dow after it has been created. By default, it uses the format
1075 ‘#{session_name}:#{window_index}.#{pane_index}’ but a different
1076 format may be specified with -F.
1077 capture-pane [-aepPqCJN] [-b buffer-name] [-E end-line] [-S start-line]
1079 [-t target-pane]
1080 (alias: capturep)
1081 Capture the contents of a pane. If -p is given, the output goes
1082 to stdout, otherwise to the buffer specified with -b or a new
1083 buffer if omitted. If -a is given, the alternate screen is used,
1084 and the history is not accessible. If no alternate screen ex‐
1085 ists, an error will be returned unless -q is given. If -e is
1086 given, the output includes escape sequences for text and back‐
1087 ground attributes. -C also escapes non-printable characters as
1088 octal \xxx. -N preserves trailing spaces at each line's end and
1089 -J preserves trailing spaces and joins any wrapped lines. -P
1090 captures only any output that the pane has received that is the
1091 beginning of an as-yet incomplete escape sequence.
1092 -S and -E specify the starting and ending line numbers, zero is
1094 the first line of the visible pane and negative numbers are lines
1095 in the history. ‘-’ to -S is the start of the history and to -E
1096 the end of the visible pane. The default is to capture only the
1097 visible contents of the pane.
1098 choose-client [-NrZ] [-F format] [-f filter] [-K key-format] [-O
1100 sort-order] [-t target-pane] [template]
1101 Put a pane into client mode, allowing a client to be selected in‐
1102 teractively from a list. Each client is shown on one line. A
1103 shortcut key is shown on the left in brackets allowing for imme‐
1104 diate choice, or the list may be navigated and an item chosen or
1105 otherwise manipulated using the keys below. -Z zooms the pane.
1106 The following keys may be used in client mode:
1107 Key Function
1109 Enter Choose selected client
1110 Up Select previous client
1111 Down Select next client
1112 C-s Search by name
1113 n Repeat last search
1114 t Toggle if client is tagged
1115 T Tag no clients
1116 C-t Tag all clients
1117 d Detach selected client
1118 D Detach tagged clients
1119 x Detach and HUP selected client
1120 X Detach and HUP tagged clients
1121 z Suspend selected client
1122 Z Suspend tagged clients
1123 f Enter a format to filter items
1124 O Change sort field
1125 r Reverse sort order
1126 v Toggle preview
1127 q Exit mode
1128 After a client is chosen, ‘%%’ is replaced by the client name in
1130 template and the result executed as a command. If template is
1131 not given, "detach-client -t '%%'" is used.
1132 -O specifies the initial sort field: one of ‘name’, ‘size’,
1134 ‘creation’, or ‘activity’. -r reverses the sort order. -f spec‐
1135 ifies an initial filter: the filter is a format - if it evaluates
1136 to zero, the item in the list is not shown, otherwise it is
1137 shown. If a filter would lead to an empty list, it is ignored.
1138 -F specifies the format for each item in the list and -K a format
1139 for each shortcut key; both are evaluated once for each line. -N
1140 starts without the preview. This command works only if at least
1141 one client is attached.
1142 choose-tree [-GNrswZ] [-F format] [-f filter] [-K key-format] [-O
1144 sort-order] [-t target-pane] [template]
1145 Put a pane into tree mode, where a session, window or pane may be
1146 chosen interactively from a tree. Each session, window or pane
1147 is shown on one line. A shortcut key is shown on the left in
1148 brackets allowing for immediate choice, or the tree may be navi‐
1149 gated and an item chosen or otherwise manipulated using the keys
1150 below. -s starts with sessions collapsed and -w with windows
1151 collapsed. -Z zooms the pane. The following keys may be used in
1152 tree mode:
1153 Key Function
1155 Enter Choose selected item
1156 Up Select previous item
1157 Down Select next item
1158 + Expand selected item
1159 - Collapse selected item
1160 M-+ Expand all items
1161 M-- Collapse all items
1162 x Kill selected item
1163 X Kill tagged items
1164 < Scroll list of previews left
1165 > Scroll list of previews right
1166 C-s Search by name
1167 m Set the marked pane
1168 M Clear the marked pane
1169 n Repeat last search
1170 t Toggle if item is tagged
1171 T Tag no items
1172 C-t Tag all items
1173 : Run a command for each tagged item
1174 f Enter a format to filter items
1175 H Jump to the starting pane
1176 O Change sort field
1177 r Reverse sort order
1178 v Toggle preview
1179 q Exit mode
1180 After a session, window or pane is chosen, the first instance of
1182 ‘%%’ and all instances of ‘%1’ are replaced by the target in
1183 template and the result executed as a command. If template is
1184 not given, "switch-client -t '%%'" is used.
1185 -O specifies the initial sort field: one of ‘index’, ‘name’, or
1187 ‘time’. -r reverses the sort order. -f specifies an initial
1188 filter: the filter is a format - if it evaluates to zero, the
1189 item in the list is not shown, otherwise it is shown. If a fil‐
1190 ter would lead to an empty list, it is ignored. -F specifies the
1191 format for each item in the tree and -K a format for each short‐
1192 cut key; both are evaluated once for each line. -N starts with‐
1193 out the preview. -G includes all sessions in any session groups
1194 in the tree rather than only the first. This command works only
1195 if at least one client is attached.
1196 customize-mode [-NZ] [-F format] [-f filter] [-t target-pane] [template]
1198 Put a pane into customize mode, where options and key bindings
1199 may be browsed and modified from a list. Option values in the
1200 list are shown for the active pane in the current window. -Z
1201 zooms the pane. The following keys may be used in customize
1202 mode:
1203 Key Function
1205 Enter Set pane, window, session or global option value
1206 Up Select previous item
1207 Down Select next item
1208 + Expand selected item
1209 - Collapse selected item
1210 M-+ Expand all items
1211 M-- Collapse all items
1212 s Set option value or key attribute
1213 S Set global option value
1214 w Set window option value, if option is for pane and
1215 window
1216 d Set an option or key to the default
1217 D Set tagged options and tagged keys to the default
1218 u Unset an option (set to default value if global) or
1219 unbind a key
1220 U Unset tagged options and unbind tagged keys
1221 C-s Search by name
1222 n Repeat last search
1223 t Toggle if item is tagged
1224 T Tag no items
1225 C-t Tag all items
1226 f Enter a format to filter items
1227 v Toggle option information
1228 q Exit mode
1229 -f specifies an initial filter: the filter is a format - if it
1231 evaluates to zero, the item in the list is not shown, otherwise
1232 it is shown. If a filter would lead to an empty list, it is ig‐
1233 nored. -F specifies the format for each item in the tree. -N
1234 starts without the option information. This command works only
1235 if at least one client is attached.
1236 display-panes [-bN] [-d duration] [-t target-client] [template]
1238 (alias: displayp)
1239 Display a visible indicator of each pane shown by target-client.
1240 See the display-panes-colour and display-panes-active-colour ses‐
1241 sion options. The indicator is closed when a key is pressed (un‐
1242 less -N is given) or duration milliseconds have passed. If -d is
1243 not given, display-panes-time is used. A duration of zero means
1244 the indicator stays until a key is pressed. While the indicator
1245 is on screen, a pane may be chosen with the ‘0’ to ‘9’ keys,
1246 which will cause template to be executed as a command with ‘%%’
1247 substituted by the pane ID. The default template is "select-pane
1248 -t '%%'". With -b, other commands are not blocked from running
1249 until the indicator is closed.
1250 find-window [-iCNrTZ] [-t target-pane] match-string
1252 (alias: findw)
1253 Search for a fnmatch(3) pattern or, with -r, regular expression
1254 match-string in window names, titles, and visible content (but
1255 not history). The flags control matching behavior: -C matches
1256 only visible window contents, -N matches only the window name and
1257 -T matches only the window title. -i makes the search ignore
1258 case. The default is -CNT. -Z zooms the pane.
1259 This command works only if at least one client is attached.
1261 join-pane [-bdfhv] [-l size] [-s src-pane] [-t dst-pane]
1263 (alias: joinp)
1264 Like split-window, but instead of splitting dst-pane and creating
1265 a new pane, split it and move src-pane into the space. This can
1266 be used to reverse break-pane. The -b option causes src-pane to
1267 be joined to left of or above dst-pane.
1268 If -s is omitted and a marked pane is present (see select-pane
1270 -m), the marked pane is used rather than the current pane.
1271 kill-pane [-a] [-t target-pane]
1273 (alias: killp)
1274 Destroy the given pane. If no panes remain in the containing
1275 window, it is also destroyed. The -a option kills all but the
1276 pane given with -t.
1277 kill-window [-a] [-t target-window]
1279 (alias: killw)
1280 Kill the current window or the window at target-window, removing
1281 it from any sessions to which it is linked. The -a option kills
1282 all but the window given with -t.
1283 last-pane [-deZ] [-t target-window]
1285 (alias: lastp)
1286 Select the last (previously selected) pane. -Z keeps the window
1287 zoomed if it was zoomed. -e enables or -d disables input to the
1288 pane.
1289 last-window [-t target-session]
1291 (alias: last)
1292 Select the last (previously selected) window. If no
1293 target-session is specified, select the last window of the cur‐
1294 rent session.
1295 link-window [-abdk] [-s src-window] [-t dst-window]
1297 (alias: linkw)
1298 Link the window at src-window to the specified dst-window. If
1299 dst-window is specified and no such window exists, the src-window
1300 is linked there. With -a or -b the window is moved to the next
1301 index after or before dst-window (existing windows are moved if
1302 necessary). If -k is given and dst-window exists, it is killed,
1303 otherwise an error is generated. If -d is given, the newly
1304 linked window is not selected.
1305 list-panes [-as] [-F format] [-f filter] [-t target]
1307 (alias: lsp)
1308 If -a is given, target is ignored and all panes on the server are
1309 listed. If -s is given, target is a session (or the current ses‐
1310 sion). If neither is given, target is a window (or the current
1311 window). -F specifies the format of each line and -f a filter.
1312 Only panes for which the filter is true are shown. See the
1313 FORMATS section.
1314 list-windows [-a] [-F format] [-f filter] [-t target-session]
1316 (alias: lsw)
1317 If -a is given, list all windows on the server. Otherwise, list
1318 windows in the current session or in target-session. -F speci‐
1319 fies the format of each line and -f a filter. Only windows for
1320 which the filter is true are shown. See the FORMATS section.
1321 move-pane [-bdfhv] [-l size] [-s src-pane] [-t dst-pane]
1323 (alias: movep)
1324 Does the same as join-pane.
1325 move-window [-abrdk] [-s src-window] [-t dst-window]
1327 (alias: movew)
1328 This is similar to link-window, except the window at src-window
1329 is moved to dst-window. With -r, all windows in the session are
1330 renumbered in sequential order, respecting the base-index option.
1331 new-window [-abdkPS] [-c start-directory] [-e environment] [-F format]
1333 [-n window-name] [-t target-window] [shell-command]
1334 (alias: neww)
1335 Create a new window. With -a or -b, the new window is inserted
1336 at the next index after or before the specified target-window,
1337 moving windows up if necessary; otherwise target-window is the
1338 new window location.
1339 If -d is given, the session does not make the new window the cur‐
1341 rent window. target-window represents the window to be created;
1342 if the target already exists an error is shown, unless the -k
1343 flag is used, in which case it is destroyed. If -S is given and
1344 a window named window-name already exists, it is selected (unless
1345 -d is also given in which case the command does nothing).
1346 shell-command is the command to execute. If shell-command is not
1348 specified, the value of the default-command option is used. -c
1349 specifies the working directory in which the new window is cre‐
1350 ated.
1351 When the shell command completes, the window closes. See the
1353 remain-on-exit option to change this behaviour.
1354 -e takes the form ‘VARIABLE=value’ and sets an environment vari‐
1356 able for the newly created window; it may be specified multiple
1357 times.
1358 The TERM environment variable must be set to ‘screen’ or ‘tmux’
1360 for all programs running inside tmux. New windows will automati‐
1361 cally have ‘TERM=screen’ added to their environment, but care
1362 must be taken not to reset this in shell start-up files or by the
1363 -e option.
1364 The -P option prints information about the new window after it
1366 has been created. By default, it uses the format
1367 ‘#{session_name}:#{window_index}’ but a different format may be
1368 specified with -F.
1369 next-layout [-t target-window]
1371 (alias: nextl)
1372 Move a window to the next layout and rearrange the panes to fit.
1373 next-window [-a] [-t target-session]
1375 (alias: next)
1376 Move to the next window in the session. If -a is used, move to
1377 the next window with an alert.
1378 pipe-pane [-IOo] [-t target-pane] [shell-command]
1380 (alias: pipep)
1381 Pipe output sent by the program in target-pane to a shell command
1382 or vice versa. A pane may only be connected to one command at a
1383 time, any existing pipe is closed before shell-command is exe‐
1384 cuted. The shell-command string may contain the special charac‐
1385 ter sequences supported by the status-left option. If no
1386 shell-command is given, the current pipe (if any) is closed.
1387 -I and -O specify which of the shell-command output streams are
1389 connected to the pane: with -I stdout is connected (so anything
1390 shell-command prints is written to the pane as if it were typed);
1391 with -O stdin is connected (so any output in the pane is piped to
1392 shell-command). Both may be used together and if neither are
1393 specified, -O is used.
1394 The -o option only opens a new pipe if no previous pipe exists,
1396 allowing a pipe to be toggled with a single key, for example:
1397 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
1399 previous-layout [-t target-window]
1401 (alias: prevl)
1402 Move to the previous layout in the session.
1403 previous-window [-a] [-t target-session]
1405 (alias: prev)
1406 Move to the previous window in the session. With -a, move to the
1407 previous window with an alert.
1408 rename-window [-t target-window] new-name
1410 (alias: renamew)
1411 Rename the current window, or the window at target-window if
1412 specified, to new-name.
1413 resize-pane [-DLMRTUZ] [-t target-pane] [-x width] [-y height]
1415 [adjustment]
1416 (alias: resizep)
1417 Resize a pane, up, down, left or right by adjustment with -U, -D,
1418 -L or -R, or to an absolute size with -x or -y. The adjustment
1419 is given in lines or columns (the default is 1); -x and -y may be
1420 a given as a number of lines or columns or followed by ‘%’ for a
1421 percentage of the window size (for example ‘-x 10%’). With -Z,
1422 the active pane is toggled between zoomed (occupying the whole of
1423 the window) and unzoomed (its normal position in the layout).
1424 -M begins mouse resizing (only valid if bound to a mouse key
1426 binding, see MOUSE SUPPORT).
1427 -T trims all lines below the current cursor position and moves
1429 lines out of the history to replace them.
1430 resize-window [-aADLRU] [-t target-window] [-x width] [-y height]
1432 [adjustment]
1433 (alias: resizew)
1434 Resize a window, up, down, left or right by adjustment with -U,
1435 -D, -L or -R, or to an absolute size with -x or -y. The
1436 adjustment is given in lines or cells (the default is 1). -A
1437 sets the size of the largest session containing the window; -a
1438 the size of the smallest. This command will automatically set
1439 window-size to manual in the window options.
1440 respawn-pane [-k] [-c start-directory] [-e environment] [-t target-pane]
1442 [shell-command]
1443 (alias: respawnp)
1444 Reactivate a pane in which the command has exited (see the
1445 remain-on-exit window option). If shell-command is not given,
1446 the command used when the pane was created or last respawned is
1447 executed. The pane must be already inactive, unless -k is given,
1448 in which case any existing command is killed. -c specifies a new
1449 working directory for the pane. The -e option has the same mean‐
1450 ing as for the new-window command.
1451 respawn-window [-k] [-c start-directory] [-e environment] [-t
1453 target-window] [shell-command]
1454 (alias: respawnw)
1455 Reactivate a window in which the command has exited (see the
1456 remain-on-exit window option). If shell-command is not given,
1457 the command used when the window was created or last respawned is
1458 executed. The window must be already inactive, unless -k is
1459 given, in which case any existing command is killed. -c speci‐
1460 fies a new working directory for the window. The -e option has
1461 the same meaning as for the new-window command.
1462 rotate-window [-DUZ] [-t target-window]
1464 (alias: rotatew)
1465 Rotate the positions of the panes within a window, either upward
1466 (numerically lower) with -U or downward (numerically higher). -Z
1467 keeps the window zoomed if it was zoomed.
1468 select-layout [-Enop] [-t target-pane] [layout-name]
1470 (alias: selectl)
1471 Choose a specific layout for a window. If layout-name is not
1472 given, the last preset layout used (if any) is reapplied. -n and
1473 -p are equivalent to the next-layout and previous-layout com‐
1474 mands. -o applies the last set layout if possible (undoes the
1475 most recent layout change). -E spreads the current pane and any
1476 panes next to it out evenly.
1477 select-pane [-DdeLlMmRUZ] [-T title] [-t target-pane]
1479 (alias: selectp)
1480 Make pane target-pane the active pane in its window. If one of
1481 -D, -L, -R, or -U is used, respectively the pane below, to the
1482 left, to the right, or above the target pane is used. -Z keeps
1483 the window zoomed if it was zoomed. -l is the same as using the
1484 last-pane command. -e enables or -d disables input to the pane.
1485 -T sets the pane title.
1486 -m and -M are used to set and clear the marked pane. There is
1488 one marked pane at a time, setting a new marked pane clears the
1489 last. The marked pane is the default target for -s to join-pane,
1490 move-pane, swap-pane and swap-window.
1491 select-window [-lnpT] [-t target-window]
1493 (alias: selectw)
1494 Select the window at target-window. -l, -n and -p are equivalent
1495 to the last-window, next-window and previous-window commands. If
1496 -T is given and the selected window is already the current win‐
1497 dow, the command behaves like last-window.
1498 split-window [-bdfhIvPZ] [-c start-directory] [-e environment] [-l size]
1500 [-t target-pane] [shell-command] [-F format]
1501 (alias: splitw)
1502 Create a new pane by splitting target-pane: -h does a horizontal
1503 split and -v a vertical split; if neither is specified, -v is as‐
1504 sumed. The -l option specifies the size of the new pane in lines
1505 (for vertical split) or in columns (for horizontal split); size
1506 may be followed by ‘%’ to specify a percentage of the available
1507 space. The -b option causes the new pane to be created to the
1508 left of or above target-pane. The -f option creates a new pane
1509 spanning the full window height (with -h) or full window width
1510 (with -v), instead of splitting the active pane. -Z zooms if the
1511 window is not zoomed, or keeps it zoomed if already zoomed.
1512 An empty shell-command ('') will create a pane with no command
1514 running in it. Output can be sent to such a pane with the
1515 display-message command. The -I flag (if shell-command is not
1516 specified or empty) will create an empty pane and forward any
1517 output from stdin to it. For example:
1518 $ make 2>&1|tmux splitw -dI &
1520 All other options have the same meaning as for the new-window
1522 command.
1523 swap-pane [-dDUZ] [-s src-pane] [-t dst-pane]
1525 (alias: swapp)
1526 Swap two panes. If -U is used and no source pane is specified
1527 with -s, dst-pane is swapped with the previous pane (before it
1528 numerically); -D swaps with the next pane (after it numerically).
1529 -d instructs tmux not to change the active pane and -Z keeps the
1530 window zoomed if it was zoomed.
1531 If -s is omitted and a marked pane is present (see select-pane
1533 -m), the marked pane is used rather than the current pane.
1534 swap-window [-d] [-s src-window] [-t dst-window]
1536 (alias: swapw)
1537 This is similar to link-window, except the source and destination
1538 windows are swapped. It is an error if no window exists at
1539 src-window. If -d is given, the new window does not become the
1540 current window.
1541 If -s is omitted and a marked pane is present (see select-pane
1543 -m), the window containing the marked pane is used rather than
1544 the current window.
1545 unlink-window [-k] [-t target-window]
1547 (alias: unlinkw)
1548 Unlink target-window. Unless -k is given, a window may be un‐
1549 linked only if it is linked to multiple sessions - windows may
1550 not be linked to no sessions; if -k is specified and the window
1551 is linked to only one session, it is unlinked and destroyed.
1552
1554 tmux allows a command to be bound to most keys, with or without a prefix
1555 key. When specifying keys, most represent themselves (for example ‘A’ to
1556 ‘Z’). Ctrl keys may be prefixed with ‘C-’ or ‘^’, Shift keys with ‘S-’
1557 and Alt (meta) with ‘M-’. In addition, the following special key names
1558 are accepted: Up, Down, Left, Right, BSpace, BTab, DC (Delete), End,
1559 Enter, Escape, F1 to F12, Home, IC (Insert), NPage/PageDown/PgDn,
1560 PPage/PageUp/PgUp, Space, and Tab. Note that to bind the ‘"’ or ‘'’
1561 keys, quotation marks are necessary, for example:
1562 bind-key '"' split-window
1564 bind-key "'" new-window
1565 A command bound to the Any key will execute for all keys which do not
1567 have a more specific binding.
1568 Commands related to key bindings are as follows:
1570 bind-key [-nr] [-N note] [-T key-table] key command [arguments]
1572 (alias: bind)
1573 Bind key key to command. Keys are bound in a key table. By de‐
1574 fault (without -T), the key is bound in the prefix key table.
1575 This table is used for keys pressed after the prefix key (for ex‐
1576 ample, by default ‘c’ is bound to new-window in the prefix table,
1577 so ‘C-b c’ creates a new window). The root table is used for
1578 keys pressed without the prefix key: binding ‘c’ to new-window in
1579 the root table (not recommended) means a plain ‘c’ will create a
1580 new window. -n is an alias for -T root. Keys may also be bound
1581 in custom key tables and the switch-client -T command used to
1582 switch to them from a key binding. The -r flag indicates this
1583 key may repeat, see the repeat-time option. -N attaches a note
1584 to the key (shown with list-keys -N).
1585 To view the default bindings and possible commands, see the
1587 list-keys command.
1588 list-keys [-1aN] [-P prefix-string -T key-table] [key]
1590 (alias: lsk)
1591 List key bindings. There are two forms: the default lists keys
1592 as bind-key commands; -N lists only keys with attached notes and
1593 shows only the key and note for each key.
1594 With the default form, all key tables are listed by default. -T
1596 lists only keys in key-table.
1597 With the -N form, only keys in the root and prefix key tables are
1599 listed by default; -T also lists only keys in key-table. -P
1600 specifies a prefix to print before each key and -1 lists only the
1601 first matching key. -a lists the command for keys that do not
1602 have a note rather than skipping them.
1603 send-keys [-FHlMRX] [-N repeat-count] [-t target-pane] key ...
1605 (alias: send)
1606 Send a key or keys to a window. Each argument key is the name of
1607 the key (such as ‘C-a’ or ‘NPage’) to send; if the string is not
1608 recognised as a key, it is sent as a series of characters. All
1609 arguments are sent sequentially from first to last. If no keys
1610 are given and the command is bound to a key, then that key is
1611 used.
1612 The -l flag disables key name lookup and processes the keys as
1614 literal UTF-8 characters. The -H flag expects each key to be a
1615 hexadecimal number for an ASCII character.
1616 The -R flag causes the terminal state to be reset.
1618 -M passes through a mouse event (only valid if bound to a mouse
1620 key binding, see MOUSE SUPPORT).
1621 -X is used to send a command into copy mode - see the WINDOWS AND
1623 PANES section. -N specifies a repeat count and -F expands for‐
1624 mats in arguments where appropriate.
1625 send-prefix [-2] [-t target-pane]
1627 Send the prefix key, or with -2 the secondary prefix key, to a
1628 window as if it was pressed.
1629 unbind-key [-anq] [-T key-table] key
1631 (alias: unbind)
1632 Unbind the command bound to key. -n and -T are the same as for
1633 bind-key. If -a is present, all key bindings are removed. The
1634 -q option prevents errors being returned.
1635
1637 The appearance and behaviour of tmux may be modified by changing the
1638 value of various options. There are four types of option: server
1639 options, session options, window options, and pane options.
1640 The tmux server has a set of global server options which do not apply to
1642 any particular window or session or pane. These are altered with the
1643 set-option -s command, or displayed with the show-options -s command.
1644 In addition, each individual session may have a set of session options,
1646 and there is a separate set of global session options. Sessions which do
1647 not have a particular option configured inherit the value from the global
1648 session options. Session options are set or unset with the set-option
1649 command and may be listed with the show-options command. The available
1650 server and session options are listed under the set-option command.
1651 Similarly, a set of window options is attached to each window and a set
1653 of pane options to each pane. Pane options inherit from window options.
1654 This means any pane option may be set as a window option to apply the op‐
1655 tion to all panes in the window without the option set, for example these
1656 commands will set the background colour to red for all panes except pane
1657 0:
1658 set -w window-style bg=red
1660 set -pt:.0 window-style bg=blue
1661 There is also a set of global window options from which any unset window
1663 or pane options are inherited. Window and pane options are altered with
1664 set-option -w and -p commands and displayed with show-option -w and -p.
1665 tmux also supports user options which are prefixed with a ‘@’. User op‐
1667 tions may have any name, so long as they are prefixed with ‘@’, and be
1668 set to any string. For example:
1669 $ tmux set -wq @foo "abc123"
1671 $ tmux show -wv @foo
1672 abc123
1673 Commands which set options are as follows:
1675 set-option [-aFgopqsuUw] [-t target-pane] option value
1677 (alias: set)
1678 Set a pane option with -p, a window option with -w, a server op‐
1679 tion with -s, otherwise a session option. If the option is not a
1680 user option, -w or -s may be unnecessary - tmux will infer the
1681 type from the option name, assuming -w for pane options. If -g
1682 is given, the global session or window option is set.
1683 -F expands formats in the option value. The -u flag unsets an
1685 option, so a session inherits the option from the global options
1686 (or with -g, restores a global option to the default). -U unsets
1687 an option (like -u) but if the option is a pane option also un‐
1688 sets the option on any panes in the window. value depends on the
1689 option and may be a number, a string, or a flag (on, off, or
1690 omitted to toggle).
1691 The -o flag prevents setting an option that is already set and
1693 the -q flag suppresses errors about unknown or ambiguous options.
1694 With -a, and if the option expects a string or a style, value is
1696 appended to the existing setting. For example:
1697 set -g status-left "foo"
1699 set -ag status-left "bar"
1700 Will result in ‘foobar’. And:
1702 set -g status-style "bg=red"
1704 set -ag status-style "fg=blue"
1705 Will result in a red background and blue foreground. Without -a,
1707 the result would be the default background and a blue foreground.
1708 show-options [-AgHpqsvw] [-t target-pane] [option]
1710 (alias: show)
1711 Show the pane options (or a single option if option is provided)
1712 with -p, the window options with -w, the server options with -s,
1713 otherwise the session options. If the option is not a user op‐
1714 tion, -w or -s may be unnecessary - tmux will infer the type from
1715 the option name, assuming -w for pane options. Global session or
1716 window options are listed if -g is used. -v shows only the op‐
1717 tion value, not the name. If -q is set, no error will be re‐
1718 turned if option is unset. -H includes hooks (omitted by de‐
1719 fault). -A includes options inherited from a parent set of op‐
1720 tions, such options are marked with an asterisk.
1721 Available server options are:
1723 backspace key
1725 Set the key sent by tmux for backspace.
1726 buffer-limit number
1728 Set the number of buffers; as new buffers are added to the top of
1729 the stack, old ones are removed from the bottom if necessary to
1730 maintain this maximum length.
1731 command-alias[] name=value
1733 This is an array of custom aliases for commands. If an unknown
1734 command matches name, it is replaced with value. For example,
1735 after:
1736 set -s command-alias[100] zoom='resize-pane -Z'
1738 Using:
1740 zoom -t:.1
1742 Is equivalent to:
1744 resize-pane -Z -t:.1
1746 Note that aliases are expanded when a command is parsed rather
1748 than when it is executed, so binding an alias with bind-key will
1749 bind the expanded form.
1750 default-terminal terminal
1752 Set the default terminal for new windows created in this session
1753 - the default value of the TERM environment variable. For tmux
1754 to work correctly, this must be set to ‘screen’, ‘tmux’ or a de‐
1755 rivative of them.
1756 copy-command shell-command
1758 Give the command to pipe to if the copy-pipe copy mode command is
1759 used without arguments.
1760 escape-time time
1762 Set the time in milliseconds for which tmux waits after an escape
1763 is input to determine if it is part of a function or meta key se‐
1764 quences. The default is 500 milliseconds.
1765 editor shell-command
1767 Set the command used when tmux runs an editor.
1768 exit-empty [on | off]
1770 If enabled (the default), the server will exit when there are no
1771 active sessions.
1772 exit-unattached [on | off]
1774 If enabled, the server will exit when there are no attached
1775 clients.
1776 extended-keys [on | off | always]
1778 When on or always, the escape sequence to enable extended keys is
1779 sent to the terminal, if tmux knows that it is supported. tmux
1780 always recognises extended keys itself. If this option is on,
1781 tmux will only forward extended keys to applications when they
1782 request them; if always, tmux will always forward the keys.
1783 focus-events [on | off]
1785 When enabled, focus events are requested from the terminal if
1786 supported and passed through to applications running in tmux.
1787 Attached clients should be detached and attached again after
1788 changing this option.
1789 history-file path
1791 If not empty, a file to which tmux will write command prompt his‐
1792 tory on exit and load it from on start.
1793 message-limit number
1795 Set the number of error or information messages to save in the
1796 message log for each client.
1797 prompt-history-limit number
1799 Set the number of history items to save in the history file for
1800 each type of command prompt.
1801 set-clipboard [on | external | off]
1803 Attempt to set the terminal clipboard content using the xterm(1)
1804 escape sequence, if there is an Ms entry in the terminfo(5) de‐
1805 scription (see the TERMINFO EXTENSIONS section).
1806 If set to on, tmux will both accept the escape sequence to create
1808 a buffer and attempt to set the terminal clipboard. If set to
1809 external, tmux will attempt to set the terminal clipboard but ig‐
1810 nore attempts by applications to set tmux buffers. If off, tmux
1811 will neither accept the clipboard escape sequence nor attempt to
1812 set the clipboard.
1813 Note that this feature needs to be enabled in xterm(1) by setting
1815 the resource:
1816 disallowedWindowOps: 20,21,SetXprop
1818 Or changing this property from the xterm(1) interactive menu when
1820 required.
1821 terminal-features[] string
1823 Set terminal features for terminal types read from terminfo(5).
1824 tmux has a set of named terminal features. Each will apply ap‐
1825 propriate changes to the terminfo(5) entry in use.
1826 tmux can detect features for a few common terminals; this option
1828 can be used to easily tell tmux about features supported by ter‐
1829 minals it cannot detect. The terminal-overrides option allows
1830 individual terminfo(5) capabilities to be set instead,
1831 terminal-features is intended for classes of functionality sup‐
1832 ported in a standard way but not reported by terminfo(5). Care
1833 must be taken to configure this only with features the terminal
1834 actually supports.
1835 This is an array option where each entry is a colon-separated
1837 string made up of a terminal type pattern (matched using
1838 fnmatch(3)) followed by a list of terminal features. The avail‐
1839 able features are:
1840 256 Supports 256 colours with the SGR escape sequences.
1842 clipboard
1844 Allows setting the system clipboard.
1845 ccolour
1847 Allows setting the cursor colour.
1848 cstyle Allows setting the cursor style.
1850 extkeys
1852 Supports extended keys.
1853 focus Supports focus reporting.
1855 margins
1857 Supports DECSLRM margins.
1858 mouse Supports xterm(1) mouse sequences.
1860 osc7 Supports the OSC 7 working directory extension.
1862 overline
1864 Supports the overline SGR attribute.
1865 rectfill
1867 Supports the DECFRA rectangle fill escape sequence.
1868 RGB Supports RGB colour with the SGR escape sequences.
1870 strikethrough
1872 Supports the strikethrough SGR escape sequence.
1873 sync Supports synchronized updates.
1875 title Supports xterm(1) title setting.
1877 usstyle
1879 Allows underscore style and colour to be set.
1880 terminal-overrides[] string
1882 Allow terminal descriptions read using terminfo(5) to be overrid‐
1883 den. Each entry is a colon-separated string made up of a termi‐
1884 nal type pattern (matched using fnmatch(3)) and a set of
1885 name=value entries.
1886 For example, to set the ‘clear’ terminfo(5) entry to ‘\e[H\e[2J’
1888 for all terminal types matching ‘rxvt*’:
1889 rxvt*:clear=\e[H\e[2J
1891 The terminal entry value is passed through strunvis(3) before in‐
1893 terpretation.
1894 user-keys[] key
1896 Set list of user-defined key escape sequences. Each item is as‐
1897 sociated with a key named ‘User0’, ‘User1’, and so on.
1898 For example:
1900 set -s user-keys[0] "\e[5;30012~"
1902 bind User0 resize-pane -L 3
1903 Available session options are:
1905 activity-action [any | none | current | other]
1907 Set action on window activity when monitor-activity is on. any
1908 means activity in any window linked to a session causes a bell or
1909 message (depending on visual-activity) in the current window of
1910 that session, none means all activity is ignored (equivalent to
1911 monitor-activity being off), current means only activity in win‐
1912 dows other than the current window are ignored and other means
1913 activity in the current window is ignored but not those in other
1914 windows.
1915 assume-paste-time milliseconds
1917 If keys are entered faster than one in milliseconds, they are as‐
1918 sumed to have been pasted rather than typed and tmux key bindings
1919 are not processed. The default is one millisecond and zero dis‐
1920 ables.
1921 base-index index
1923 Set the base index from which an unused index should be searched
1924 when a new window is created. The default is zero.
1925 bell-action [any | none | current | other]
1927 Set action on a bell in a window when monitor-bell is on. The
1928 values are the same as those for activity-action.
1929 default-command shell-command
1931 Set the command used for new windows (if not specified when the
1932 window is created) to shell-command, which may be any sh(1) com‐
1933 mand. The default is an empty string, which instructs tmux to
1934 create a login shell using the value of the default-shell option.
1935 default-shell path
1937 Specify the default shell. This is used as the login shell for
1938 new windows when the default-command option is set to empty, and
1939 must be the full path of the executable. When started tmux tries
1940 to set a default value from the first suitable of the SHELL envi‐
1941 ronment variable, the shell returned by getpwuid(3), or /bin/sh.
1942 This option should be configured when tmux is used as a login
1943 shell.
1944 default-size XxY
1946 Set the default size of new windows when the window-size option
1947 is set to manual or when a session is created with new-session
1948 -d. The value is the width and height separated by an ‘x’ char‐
1949 acter. The default is 80x24.
1950 destroy-unattached [on | off]
1952 If enabled and the session is no longer attached to any clients,
1953 it is destroyed.
1954 detach-on-destroy [off | on | no-detached]
1956 If on (the default), the client is detached when the session it
1957 is attached to is destroyed. If off, the client is switched to
1958 the most recently active of the remaining sessions. If
1959 no-detached, the client is detached only if there are no detached
1960 sessions; if detached sessions exist, the client is switched to
1961 the most recently active.
1962 display-panes-active-colour colour
1964 Set the colour used by the display-panes command to show the in‐
1965 dicator for the active pane.
1966 display-panes-colour colour
1968 Set the colour used by the display-panes command to show the in‐
1969 dicators for inactive panes.
1970 display-panes-time time
1972 Set the time in milliseconds for which the indicators shown by
1973 the display-panes command appear.
1974 display-time time
1976 Set the amount of time for which status line messages and other
1977 on-screen indicators are displayed. If set to 0, messages and
1978 indicators are displayed until a key is pressed. time is in mil‐
1979 liseconds.
1980 history-limit lines
1982 Set the maximum number of lines held in window history. This
1983 setting applies only to new windows - existing window histories
1984 are not resized and retain the limit at the point they were cre‐
1985 ated.
1986 key-table key-table
1988 Set the default key table to key-table instead of root.
1989 lock-after-time number
1991 Lock the session (like the lock-session command) after number
1992 seconds of inactivity. The default is not to lock (set to 0).
1993 lock-command shell-command
1995 Command to run when locking each client. The default is to run
1996 lock(1) with -np.
1997 message-command-style style
1999 Set status line message command style. This is used for the com‐
2000 mand prompt with vi(1) keys when in command mode. For how to
2001 specify style, see the STYLES section.
2002 message-style style
2004 Set status line message style. This is used for messages and for
2005 the command prompt. For how to specify style, see the STYLES
2006 section.
2007 mouse [on | off]
2009 If on, tmux captures the mouse and allows mouse events to be
2010 bound as key bindings. See the MOUSE SUPPORT section for de‐
2011 tails.
2012 prefix key
2014 Set the key accepted as a prefix key. In addition to the stan‐
2015 dard keys described under KEY BINDINGS, prefix can be set to the
2016 special key ‘None’ to set no prefix.
2017 prefix2 key
2019 Set a secondary key accepted as a prefix key. Like prefix,
2020 prefix2 can be set to ‘None’.
2021 renumber-windows [on | off]
2023 If on, when a window is closed in a session, automatically renum‐
2024 ber the other windows in numerical order. This respects the
2025 base-index option if it has been set. If off, do not renumber
2026 the windows.
2027 repeat-time time
2029 Allow multiple commands to be entered without pressing the pre‐
2030 fix-key again in the specified time milliseconds (the default is
2031 500). Whether a key repeats may be set when it is bound using
2032 the -r flag to bind-key. Repeat is enabled for the default keys
2033 bound to the resize-pane command.
2034 set-titles [on | off]
2036 Attempt to set the client terminal title using the tsl and fsl
2037 terminfo(5) entries if they exist. tmux automatically sets these
2038 to the \e]0;...\007 sequence if the terminal appears to be
2039 xterm(1). This option is off by default.
2040 set-titles-string string
2042 String used to set the client terminal title if set-titles is on.
2043 Formats are expanded, see the FORMATS section.
2044 silence-action [any | none | current | other]
2046 Set action on window silence when monitor-silence is on. The
2047 values are the same as those for activity-action.
2048 status [off | on | 2 | 3 | 4 | 5]
2050 Show or hide the status line or specify its size. Using on gives
2051 a status line one row in height; 2, 3, 4 or 5 more rows.
2052 status-format[] format
2054 Specify the format to be used for each line of the status line.
2055 The default builds the top status line from the various individ‐
2056 ual status options below.
2057 status-interval interval
2059 Update the status line every interval seconds. By default, up‐
2060 dates will occur every 15 seconds. A setting of zero disables
2061 redrawing at interval.
2062 status-justify [left | centre | right | absolute-centre]
2064 Set the position of the window list in the status line: left,
2065 centre or right. centre puts the window list in the relative
2066 centre of the available free space; absolute-centre uses the cen‐
2067 tre of the entire horizontal space.
2068 status-keys [vi | emacs]
2070 Use vi or emacs-style key bindings in the status line, for exam‐
2071 ple at the command prompt. The default is emacs, unless the
2072 VISUAL or EDITOR environment variables are set and contain the
2073 string ‘vi’.
2074 status-left string
2076 Display string (by default the session name) to the left of the
2077 status line. string will be passed through strftime(3). Also
2078 see the FORMATS and STYLES sections.
2079 For details on how the names and titles can be set see the NAMES
2081 AND TITLES section.
2082 Examples are:
2084 #(sysctl vm.loadavg)
2086 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
2087 The default is ‘[#S] ’.
2089 status-left-length length
2091 Set the maximum length of the left component of the status line.
2092 The default is 10.
2093 status-left-style style
2095 Set the style of the left part of the status line. For how to
2096 specify style, see the STYLES section.
2097 status-position [top | bottom]
2099 Set the position of the status line.
2100 status-right string
2102 Display string to the right of the status line. By default, the
2103 current pane title in double quotes, the date and the time are
2104 shown. As with status-left, string will be passed to strftime(3)
2105 and character pairs are replaced.
2106 status-right-length length
2108 Set the maximum length of the right component of the status line.
2109 The default is 40.
2110 status-right-style style
2112 Set the style of the right part of the status line. For how to
2113 specify style, see the STYLES section.
2114 status-style style
2116 Set status line style. For how to specify style, see the STYLES
2117 section.
2118 update-environment[] variable
2120 Set list of environment variables to be copied into the session
2121 environment when a new session is created or an existing session
2122 is attached. Any variables that do not exist in the source envi‐
2123 ronment are set to be removed from the session environment (as if
2124 -r was given to the set-environment command).
2125 visual-activity [on | off | both]
2127 If on, display a message instead of sending a bell when activity
2128 occurs in a window for which the monitor-activity window option
2129 is enabled. If set to both, a bell and a message are produced.
2130 visual-bell [on | off | both]
2132 If on, a message is shown on a bell in a window for which the
2133 monitor-bell window option is enabled instead of it being passed
2134 through to the terminal (which normally makes a sound). If set
2135 to both, a bell and a message are produced. Also see the
2136 bell-action option.
2137 visual-silence [on | off | both]
2139 If monitor-silence is enabled, prints a message after the inter‐
2140 val has expired on a given window instead of sending a bell. If
2141 set to both, a bell and a message are produced.
2142 word-separators string
2144 Sets the session's conception of what characters are considered
2145 word separators, for the purposes of the next and previous word
2146 commands in copy mode.
2147 Available window options are:
2149 aggressive-resize [on | off]
2151 Aggressively resize the chosen window. This means that tmux will
2152 resize the window to the size of the smallest or largest session
2153 (see the window-size option) for which it is the current window,
2154 rather than the session to which it is attached. The window may
2155 resize when the current window is changed on another session;
2156 this option is good for full-screen programs which support
2157 SIGWINCH and poor for interactive programs such as shells.
2158 automatic-rename [on | off]
2160 Control automatic window renaming. When this setting is enabled,
2161 tmux will rename the window automatically using the format speci‐
2162 fied by automatic-rename-format. This flag is automatically dis‐
2163 abled for an individual window when a name is specified at cre‐
2164 ation with new-window or new-session, or later with
2165 rename-window, or with a terminal escape sequence. It may be
2166 switched off globally with:
2167 set-option -wg automatic-rename off
2169 automatic-rename-format format
2171 The format (see FORMATS) used when the automatic-rename option is
2172 enabled.
2173 clock-mode-colour colour
2175 Set clock colour.
2176 clock-mode-style [12 | 24]
2178 Set clock hour format.
2179 fill-character character
2181 Set the character used to fill areas of the terminal unused by a
2182 window.
2183 main-pane-height height
2185 main-pane-width width
2186 Set the width or height of the main (left or top) pane in the
2187 main-horizontal or main-vertical layouts. If suffixed by ‘%’,
2188 this is a percentage of the window size.
2189 copy-mode-match-style style
2191 Set the style of search matches in copy mode. For how to specify
2192 style, see the STYLES section.
2193 copy-mode-mark-style style
2195 Set the style of the line containing the mark in copy mode. For
2196 how to specify style, see the STYLES section.
2197 copy-mode-current-match-style style
2199 Set the style of the current search match in copy mode. For how
2200 to specify style, see the STYLES section.
2201 mode-keys [vi | emacs]
2203 Use vi or emacs-style key bindings in copy mode. The default is
2204 emacs, unless VISUAL or EDITOR contains ‘vi’.
2205 mode-style style
2207 Set window modes style. For how to specify style, see the STYLES
2208 section.
2209 monitor-activity [on | off]
2211 Monitor for activity in the window. Windows with activity are
2212 highlighted in the status line.
2213 monitor-bell [on | off]
2215 Monitor for a bell in the window. Windows with a bell are high‐
2216 lighted in the status line.
2217 monitor-silence [interval]
2219 Monitor for silence (no activity) in the window within interval
2220 seconds. Windows that have been silent for the interval are
2221 highlighted in the status line. An interval of zero disables the
2222 monitoring.
2223 other-pane-height height
2225 Set the height of the other panes (not the main pane) in the
2226 main-horizontal layout. If this option is set to 0 (the de‐
2227 fault), it will have no effect. If both the main-pane-height and
2228 other-pane-height options are set, the main pane will grow taller
2229 to make the other panes the specified height, but will never
2230 shrink to do so. If suffixed by ‘%’, this is a percentage of the
2231 window size.
2232 other-pane-width width
2234 Like other-pane-height, but set the width of other panes in the
2235 main-vertical layout.
2236 pane-active-border-style style
2238 Set the pane border style for the currently active pane. For how
2239 to specify style, see the STYLES section. Attributes are ig‐
2240 nored.
2241 pane-base-index index
2243 Like base-index, but set the starting index for pane numbers.
2244 pane-border-format format
2246 Set the text shown in pane border status lines.
2247 pane-border-indicators [off | colour | arrows | both]
2249 Indicate active pane by colouring only half of the border in win‐
2250 dows with exactly two panes, by displaying arrow markers, by
2251 drawing both or neither.
2252 pane-border-lines type
2254 Set the type of characters used for drawing pane borders. type
2255 may be one of:
2256 single single lines using ACS or UTF-8 characters
2258 double double lines using UTF-8 characters
2260 heavy heavy lines using UTF-8 characters
2262 simple simple ASCII characters
2264 number the pane number
2266 ‘double’ and ‘heavy’ will fall back to standard ACS line drawing
2268 when UTF-8 is not supported.
2269 pane-border-status [off | top | bottom]
2271 Turn pane border status lines off or set their position.
2272 pane-border-style style
2274 Set the pane border style for panes aside from the active pane.
2275 For how to specify style, see the STYLES section. Attributes are
2276 ignored.
2277 popup-style style
2279 Set the popup style. For how to specify style, see the STYLES
2280 section. Attributes are ignored.
2281 popup-border-style style
2283 Set the popup border style. For how to specify style, see the
2284 STYLES section. Attributes are ignored.
2285 popup-border-lines type
2287 Set the type of characters used for drawing popup borders. type
2288 may be one of:
2289 single single lines using ACS or UTF-8 characters (default)
2291 rounded
2293 variation of single with rounded corners using UTF-8
2294 characters
2295 double double lines using UTF-8 characters
2297 heavy heavy lines using UTF-8 characters
2299 simple simple ASCII characters
2301 padded simple ASCII space character
2303 none no border
2305 ‘double’ and ‘heavy’ will fall back to standard ACS line drawing
2307 when UTF-8 is not supported.
2308 window-status-activity-style style
2310 Set status line style for windows with an activity alert. For
2311 how to specify style, see the STYLES section.
2312 window-status-bell-style style
2314 Set status line style for windows with a bell alert. For how to
2315 specify style, see the STYLES section.
2316 window-status-current-format string
2318 Like window-status-format, but is the format used when the window
2319 is the current window.
2320 window-status-current-style style
2322 Set status line style for the currently active window. For how
2323 to specify style, see the STYLES section.
2324 window-status-format string
2326 Set the format in which the window is displayed in the status
2327 line window list. See the FORMATS and STYLES sections.
2328 window-status-last-style style
2330 Set status line style for the last active window. For how to
2331 specify style, see the STYLES section.
2332 window-status-separator string
2334 Sets the separator drawn between windows in the status line. The
2335 default is a single space character.
2336 window-status-style style
2338 Set status line style for a single window. For how to specify
2339 style, see the STYLES section.
2340 window-size largest | smallest | manual | latest
2342 Configure how tmux determines the window size. If set to
2343 largest, the size of the largest attached session is used; if
2344 smallest, the size of the smallest. If manual, the size of a new
2345 window is set from the default-size option and windows are re‐
2346 sized automatically. With latest, tmux uses the size of the
2347 client that had the most recent activity. See also the
2348 resize-window command and the aggressive-resize option.
2349 wrap-search [on | off]
2351 If this option is set, searches will wrap around the end of the
2352 pane contents. The default is on.
2353 Available pane options are:
2355 allow-passthrough [on | off]
2357 Allow programs in the pane to bypass tmux using a terminal escape
2358 sequence (\ePtmux;...\e\\).
2359 allow-rename [on | off]
2361 Allow programs in the pane to change the window name using a ter‐
2362 minal escape sequence (\ek...\e\\).
2363 alternate-screen [on | off]
2365 This option configures whether programs running inside the pane
2366 may use the terminal alternate screen feature, which allows the
2367 smcup and rmcup terminfo(5) capabilities. The alternate screen
2368 feature preserves the contents of the window when an interactive
2369 application starts and restores it on exit, so that any output
2370 visible before the application starts reappears unchanged after
2371 it exits.
2372 cursor-colour colour
2374 Set the colour of the cursor.
2375 pane-colours[] colour
2377 The default colour palette. Each entry in the array defines the
2378 colour tmux uses when the colour with that index is requested.
2379 The index may be from zero to 255.
2380 cursor-style style
2382 Set the style of the cursor. Available styles are: default,
2383 blinking-block, block, blinking-underline, underline,
2384 blinking-bar, bar.
2385 remain-on-exit [on | off | failed]
2387 A pane with this flag set is not destroyed when the program run‐
2388 ning in it exits. If set to failed, then only when the program
2389 exit status is not zero. The pane may be reactivated with the
2390 respawn-pane command.
2391 remain-on-exit-format string
2393 Set the text shown at the bottom of exited panes when
2394 remain-on-exit is enabled.
2395 scroll-on-clear [on | off]
2397 When the entire screen is cleared and this option is on, scroll
2398 the contents of the screen into history before clearing it.
2399 synchronize-panes [on | off]
2401 Duplicate input to all other panes in the same window where this
2402 option is also on (only for panes that are not in any mode).
2403 window-active-style style
2405 Set the pane style when it is the active pane. For how to spec‐
2406 ify style, see the STYLES section.
2407 window-style style
2409 Set the pane style. For how to specify style, see the STYLES
2410 section.
2411
2413 tmux allows commands to run on various triggers, called hooks. Most tmux
2414 commands have an after hook and there are a number of hooks not associ‐
2415 ated with commands.
2416 Hooks are stored as array options, members of the array are executed in
2418 order when the hook is triggered. Like options different hooks may be
2419 global or belong to a session, window or pane. Hooks may be configured
2420 with the set-hook or set-option commands and displayed with show-hooks or
2421 show-options -H. The following two commands are equivalent:
2422 set-hook -g pane-mode-changed[42] 'set -g status-left-style bg=red'
2424 set-option -g pane-mode-changed[42] 'set -g status-left-style bg=red'
2425 Setting a hook without specifying an array index clears the hook and sets
2427 the first member of the array.
2428 A command's after hook is run after it completes, except when the command
2430 is run as part of a hook itself. They are named with an ‘after-’ prefix.
2431 For example, the following command adds a hook to select the even-verti‐
2432 cal layout after every split-window:
2433 set-hook -g after-split-window "selectl even-vertical"
2435 All the notifications listed in the CONTROL MODE section are hooks (with‐
2437 out any arguments), except %exit. The following additional hooks are
2438 available:
2439 alert-activity Run when a window has activity. See
2441 monitor-activity.
2442 alert-bell Run when a window has received a bell. See
2444 monitor-bell.
2445 alert-silence Run when a window has been silent. See
2447 monitor-silence.
2448 client-active Run when a client becomes the latest active
2450 client of its session.
2451 client-attached Run when a client is attached.
2453 client-detached Run when a client is detached
2455 client-focus-in Run when focus enters a client
2457 client-focus-out Run when focus exits a client
2459 client-resized Run when a client is resized.
2461 client-session-changed Run when a client's attached session is changed.
2463 pane-died Run when the program running in a pane exits, but
2465 remain-on-exit is on so the pane has not closed.
2466 pane-exited Run when the program running in a pane exits.
2468 pane-focus-in Run when the focus enters a pane, if the
2470 focus-events option is on.
2471 pane-focus-out Run when the focus exits a pane, if the
2473 focus-events option is on.
2474 pane-set-clipboard Run when the terminal clipboard is set using the
2476 xterm(1) escape sequence.
2477 session-created Run when a new session created.
2479 session-closed Run when a session closed.
2481 session-renamed Run when a session is renamed.
2483 window-linked Run when a window is linked into a session.
2485 window-renamed Run when a window is renamed.
2487 window-resized Run when a window is resized. This may be after
2489 the client-resized hook is run.
2490 window-unlinked Run when a window is unlinked from a session.
2492 Hooks are managed with these commands:
2494 set-hook [-agpRuw] [-t target-pane] hook-name command
2496 Without -R, sets (or with -u unsets) hook hook-name to command.
2497 The flags are the same as for set-option.
2498 With -R, run hook-name immediately.
2500 show-hooks [-gpw] [-t target-pane]
2502 Shows hooks. The flags are the same as for show-options.
2503
2505 If the mouse option is on (the default is off), tmux allows mouse events
2506 to be bound as keys. The name of each key is made up of a mouse event
2507 (such as ‘MouseUp1’) and a location suffix, one of the following:
2508 Pane the contents of a pane
2510 Border a pane border
2511 Status the status line window list
2512 StatusLeft the left part of the status line
2513 StatusRight the right part of the status line
2514 StatusDefault any other part of the status line
2515 The following mouse events are available:
2517 WheelUp WheelDown
2519 MouseDown1 MouseUp1 MouseDrag1 MouseDragEnd1
2520 MouseDown2 MouseUp2 MouseDrag2 MouseDragEnd2
2521 MouseDown3 MouseUp3 MouseDrag3 MouseDragEnd3
2522 SecondClick1 SecondClick2 SecondClick3
2523 DoubleClick1 DoubleClick2 DoubleClick3
2524 TripleClick1 TripleClick2 TripleClick3
2525 The ‘SecondClick’ events are fired for the second click of a double
2527 click, even if there may be a third click which will fire ‘TripleClick’
2528 instead of ‘DoubleClick’.
2529 Each should be suffixed with a location, for example ‘MouseDown1Status’.
2531 The special token ‘{mouse}’ or ‘=’ may be used as target-window or
2533 target-pane in commands bound to mouse key bindings. It resolves to the
2534 window or pane over which the mouse event took place (for example, the
2535 window in the status line over which button 1 was released for a
2536 ‘MouseUp1Status’ binding, or the pane over which the wheel was scrolled
2537 for a ‘WheelDownPane’ binding).
2538 The send-keys -M flag may be used to forward a mouse event to a pane.
2540 The default key bindings allow the mouse to be used to select and resize
2542 panes, to copy text and to change window using the status line. These
2543 take effect if the mouse option is turned on.
2544
2546 Certain commands accept the -F flag with a format argument. This is a
2547 string which controls the output format of the command. Format variables
2548 are enclosed in ‘#{’ and ‘}’, for example ‘#{session_name}’. The possi‐
2549 ble variables are listed in the table below, or the name of a tmux option
2550 may be used for an option's value. Some variables have a shorter alias
2551 such as ‘#S’; ‘##’ is replaced by a single ‘#’, ‘#,’ by a ‘,’ and ‘#}’ by
2552 a ‘}’.
2553 Conditionals are available by prefixing with ‘?’ and separating two al‐
2555 ternatives with a comma; if the specified variable exists and is not
2556 zero, the first alternative is chosen, otherwise the second is used. For
2557 example ‘#{?session_attached,attached,not attached}’ will include the
2558 string ‘attached’ if the session is attached and the string ‘not
2559 attached’ if it is unattached, or ‘#{?automatic-rename,yes,no}’ will in‐
2560 clude ‘yes’ if automatic-rename is enabled, or ‘no’ if not. Conditionals
2561 can be nested arbitrarily. Inside a conditional, ‘,’ and ‘}’ must be es‐
2562 caped as ‘#,’ and ‘#}’, unless they are part of a ‘#{...}’ replacement.
2563 For example:
2564 #{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W .
2566 String comparisons may be expressed by prefixing two comma-separated al‐
2568 ternatives by ‘==’, ‘!=’, ‘<’, ‘>’, ‘<=’ or ‘>=’ and a colon. For exam‐
2569 ple ‘#{==:#{host},myhost}’ will be replaced by ‘1’ if running on
2570 ‘myhost’, otherwise by ‘0’. ‘||’ and ‘&&’ evaluate to true if either or
2571 both of two comma-separated alternatives are true, for example
2572 ‘#{||:#{pane_in_mode},#{alternate_on}}’.
2573 An ‘m’ specifies an fnmatch(3) or regular expression comparison. The
2575 first argument is the pattern and the second the string to compare. An
2576 optional argument specifies flags: ‘r’ means the pattern is a regular ex‐
2577 pression instead of the default fnmatch(3) pattern, and ‘i’ means to ig‐
2578 nore case. For example: ‘#{m:*foo*,#{host}}’ or ‘#{m/ri:^A,MYVAR}’. A
2579 ‘C’ performs a search for an fnmatch(3) pattern or regular expression in
2580 the pane content and evaluates to zero if not found, or a line number if
2581 found. Like ‘m’, an ‘r’ flag means search for a regular expression and
2582 ‘i’ ignores case. For example: ‘#{C/r:^Start}’
2583 Numeric operators may be performed by prefixing two comma-separated al‐
2585 ternatives with an ‘e’ and an operator. An optional ‘f’ flag may be
2586 given after the operator to use floating point numbers, otherwise inte‐
2587 gers are used. This may be followed by a number giving the number of
2588 decimal places to use for the result. The available operators are: addi‐
2589 tion ‘+’, subtraction ‘-’, multiplication ‘*’, division ‘/’, modulus ‘m’
2590 or ‘%’ (note that ‘%’ must be escaped as ‘%%’ in formats which are also
2591 expanded by strftime(3)) and numeric comparison operators ‘==’, ‘!=’,
2592 ‘<’, ‘<=’, ‘>’ and ‘>=’. For example, ‘#{e|*|f|4:5.5,3}’ multiplies 5.5
2593 by 3 for a result with four decimal places and ‘#{e|%%:7,3}’ returns the
2594 modulus of 7 and 3. ‘a’ replaces a numeric argument by its ASCII equiva‐
2595 lent, so ‘#{a:98}’ results in ‘b’. ‘c’ replaces a tmux colour by its
2596 six-digit hexadecimal RGB value.
2597 A limit may be placed on the length of the resultant string by prefixing
2599 it by an ‘=’, a number and a colon. Positive numbers count from the
2600 start of the string and negative from the end, so ‘#{=5:pane_title}’ will
2601 include at most the first five characters of the pane title, or
2602 ‘#{=-5:pane_title}’ the last five characters. A suffix or prefix may be
2603 given as a second argument - if provided then it is appended or prepended
2604 to the string if the length has been trimmed, for example
2605 ‘#{=/5/...:pane_title}’ will append ‘...’ if the pane title is more than
2606 five characters. Similarly, ‘p’ pads the string to a given width, for
2607 example ‘#{p10:pane_title}’ will result in a width of at least 10 charac‐
2608 ters. A positive width pads on the left, a negative on the right. ‘n’
2609 expands to the length of the variable and ‘w’ to its width when dis‐
2610 played, for example ‘#{n:window_name}’.
2611 Prefixing a time variable with ‘t:’ will convert it to a string, so if
2613 ‘#{window_activity}’ gives ‘1445765102’, ‘#{t:window_activity}’ gives
2614 ‘Sun Oct 25 09:25:02 2015’. Adding ‘p (’ ‘`t/p`’) will use shorter but
2615 less accurate time format for times in the past. A custom format may be
2616 given using an ‘f’ suffix (note that ‘%’ must be escaped as ‘%%’ if the
2617 format is separately being passed through strftime(3), for example in the
2618 status-left option): ‘#{t/f/%%H#:%%M:window_activity}’, see strftime(3).
2619 The ‘b:’ and ‘d:’ prefixes are basename(3) and dirname(3) of the variable
2621 respectively. ‘q:’ will escape sh(1) special characters or with a ‘h’
2622 suffix, escape hash characters (so ‘#’ becomes ‘##’). ‘E:’ will expand
2623 the format twice, for example ‘#{E:status-left}’ is the result of expand‐
2624 ing the content of the status-left option rather than the option itself.
2625 ‘T:’ is like ‘E:’ but also expands strftime(3) specifiers. ‘S:’, ‘W:’ or
2626 ‘P:’ will loop over each session, window or pane and insert the format
2627 once for each. For windows and panes, two comma-separated formats may be
2628 given: the second is used for the current window or active pane. For ex‐
2629 ample, to get a list of windows formatted like the status line:
2630 #{W:#{E:window-status-format} ,#{E:window-status-current-format} }
2632 ‘N:’ checks if a window (without any suffix or with the ‘w’ suffix) or a
2634 session (with the ‘s’ suffix) name exists, for example ‘`N/w:foo`’ is re‐
2635 placed with 1 if a window named ‘foo’ exists.
2636 A prefix of the form ‘s/foo/bar/:’ will substitute ‘foo’ with ‘bar’
2638 throughout. The first argument may be an extended regular expression and
2639 a final argument may be ‘i’ to ignore case, for example ‘s/a(.)/\1x/i:’
2640 would change ‘abABab’ into ‘bxBxbx’.
2641 In addition, the last line of a shell command's output may be inserted
2643 using ‘#()’. For example, ‘#(uptime)’ will insert the system's uptime.
2644 When constructing formats, tmux does not wait for ‘#()’ commands to fin‐
2645 ish; instead, the previous result from running the same command is used,
2646 or a placeholder if the command has not been run before. If the command
2647 hasn't exited, the most recent line of output will be used, but the sta‐
2648 tus line will not be updated more than once a second. Commands are exe‐
2649 cuted using /bin/sh and with the tmux global environment set (see the
2650 GLOBAL AND SESSION ENVIRONMENT section).
2651 An ‘l’ specifies that a string should be interpreted literally and not
2653 expanded. For example ‘#{l:#{?pane_in_mode,yes,no}}’ will be replaced by
2654 ‘#{?pane_in_mode,yes,no}’.
2655 The following variables are available, where appropriate:
2657 Variable name Alias Replaced with
2659 active_window_index Index of active window in session
2660 alternate_on 1 if pane is in alternate screen
2661 alternate_saved_x Saved cursor X in alternate screen
2662 alternate_saved_y Saved cursor Y in alternate screen
2663 buffer_created Time buffer created
2664 buffer_name Name of buffer
2665 buffer_sample Sample of start of buffer
2666 buffer_size Size of the specified buffer in bytes
2667 client_activity Time client last had activity
2668 client_cell_height Height of each client cell in pixels
2669 client_cell_width Width of each client cell in pixels
2670 client_control_mode 1 if client is in control mode
2671 client_created Time client created
2672 client_discarded Bytes discarded when client behind
2673 client_flags List of client flags
2674 client_height Height of client
2675 client_key_table Current key table
2676 client_last_session Name of the client's last session
2677 client_name Name of client
2678 client_pid PID of client process
2679 client_prefix 1 if prefix key has been pressed
2680 client_readonly 1 if client is read-only
2681 client_session Name of the client's session
2682 client_termfeatures Terminal features of client, if any
2683 client_termname Terminal name of client
2684 client_termtype Terminal type of client, if available
2685 client_tty Pseudo terminal of client
2686 client_uid UID of client process
2687 client_user User of client process
2688 client_utf8 1 if client supports UTF-8
2689 client_width Width of client
2690 client_written Bytes written to client
2691 command Name of command in use, if any
2692 command_list_alias Command alias if listing commands
2693 command_list_name Command name if listing commands
2694 command_list_usage Command usage if listing commands
2695 config_files List of configuration files loaded
2696 copy_cursor_line Line the cursor is on in copy mode
2697 copy_cursor_word Word under cursor in copy mode
2698 copy_cursor_x Cursor X position in copy mode
2699 copy_cursor_y Cursor Y position in copy mode
2700 current_file Current configuration file
2701 cursor_character Character at cursor in pane
2702 cursor_flag Pane cursor flag
2703 cursor_x Cursor X position in pane
2704 cursor_y Cursor Y position in pane
2705 history_bytes Number of bytes in window history
2706 history_limit Maximum window history lines
2707 history_size Size of history in lines
2708 hook Name of running hook, if any
2709 hook_client Name of client where hook was run, if any
2710 hook_pane ID of pane where hook was run, if any
2711 hook_session ID of session where hook was run, if any
2712 hook_session_name Name of session where hook was run, if
2713 any
2714 hook_window ID of window where hook was run, if any
2715 hook_window_name Name of window where hook was run, if any
2716 host #H Hostname of local host
2717 host_short #h Hostname of local host (no domain name)
2718 insert_flag Pane insert flag
2719 keypad_cursor_flag Pane keypad cursor flag
2720 keypad_flag Pane keypad flag
2721 last_window_index Index of last window in session
2722 line Line number in the list
2723 mouse_all_flag Pane mouse all flag
2724 mouse_any_flag Pane mouse any flag
2725 mouse_button_flag Pane mouse button flag
2726 mouse_line Line under mouse, if any
2727 mouse_sgr_flag Pane mouse SGR flag
2728 mouse_standard_flag Pane mouse standard flag
2729 mouse_utf8_flag Pane mouse UTF-8 flag
2730 mouse_word Word under mouse, if any
2731 mouse_x Mouse X position, if any
2732 mouse_y Mouse Y position, if any
2733 next_session_id Unique session ID for next new session
2734 origin_flag Pane origin flag
2735 pane_active 1 if active pane
2736 pane_at_bottom 1 if pane is at the bottom of window
2737 pane_at_left 1 if pane is at the left of window
2738 pane_at_right 1 if pane is at the right of window
2739 pane_at_top 1 if pane is at the top of window
2740 pane_bg Pane background colour
2741 pane_bottom Bottom of pane
2742 pane_current_command Current command if available
2743 pane_current_path Current path if available
2744 pane_dead 1 if pane is dead
2745 pane_dead_signal Exit signal of process in dead pane
2746 pane_dead_status Exit status of process in dead pane
2747 pane_dead_time Exit time of process in dead pane
2748 pane_fg Pane foreground colour
2749 pane_format 1 if format is for a pane
2750 pane_height Height of pane
2751 pane_id #D Unique pane ID
2752 pane_in_mode 1 if pane is in a mode
2753 pane_index #P Index of pane
2754 pane_input_off 1 if input to pane is disabled
2755 pane_last 1 if last pane
2756 pane_left Left of pane
2757 pane_marked 1 if this is the marked pane
2758 pane_marked_set 1 if a marked pane is set
2759 pane_mode Name of pane mode, if any
2760 pane_path Path of pane (can be set by application)
2761 pane_pid PID of first process in pane
2762 pane_pipe 1 if pane is being piped
2763 pane_right Right of pane
2764 pane_search_string Last search string in copy mode
2765 pane_start_command Command pane started with
2766 pane_start_path Path pane started with
2767 pane_synchronized 1 if pane is synchronized
2768 pane_tabs Pane tab positions
2769 pane_title #T Title of pane (can be set by application)
2770 pane_top Top of pane
2771 pane_tty Pseudo terminal of pane
2772 pane_width Width of pane
2773 pid Server PID
2774 rectangle_toggle 1 if rectangle selection is activated
2775 scroll_position Scroll position in copy mode
2776 scroll_region_lower Bottom of scroll region in pane
2777 scroll_region_upper Top of scroll region in pane
2778 search_match Search match if any
2779 search_present 1 if search started in copy mode
2780 selection_active 1 if selection started and changes with
2781 the cursor in copy mode
2782 selection_end_x X position of the end of the selection
2783 selection_end_y Y position of the end of the selection
2784 selection_present 1 if selection started in copy mode
2785 selection_start_x X position of the start of the selection
2786 selection_start_y Y position of the start of the selection
2787 session_activity Time of session last activity
2788 session_alerts List of window indexes with alerts
2789 session_attached Number of clients session is attached to
2790 session_attached_list List of clients session is attached to
2791 session_created Time session created
2792 session_format 1 if format is for a session
2793 session_group Name of session group
2794 session_group_attached Number of clients sessions in group are
2795 attached to
2796 session_group_attached_list List of clients sessions in group are
2797 attached to
2798 session_group_list List of sessions in group
2799 session_group_many_attached 1 if multiple clients attached to
2800 sessions in group
2801 session_group_size Size of session group
2802 session_grouped 1 if session in a group
2803 session_id Unique session ID
2804 session_last_attached Time session last attached
2805 session_many_attached 1 if multiple clients attached
2806 session_marked 1 if this session contains the marked
2807 pane
2808 session_name #S Name of session
2809 session_path Working directory of session
2810 session_stack Window indexes in most recent order
2811 session_windows Number of windows in session
2812 socket_path Server socket path
2813 start_time Server start time
2814 uid Server UID
2815 user Server user
2816 version Server version
2817 window_active 1 if window active
2818 window_active_clients Number of clients viewing this window
2819 window_active_clients_list List of clients viewing this window
2820 window_active_sessions Number of sessions on which this window
2821 is active
2822 window_active_sessions_list List of sessions on which this window is
2823 active
2824 window_activity Time of window last activity
2825 window_activity_flag 1 if window has activity
2826 window_bell_flag 1 if window has bell
2827 window_bigger 1 if window is larger than client
2828 window_cell_height Height of each cell in pixels
2829 window_cell_width Width of each cell in pixels
2830 window_end_flag 1 if window has the highest index
2831 window_flags #F Window flags with # escaped as ##
2832 window_format 1 if format is for a window
2833 window_height Height of window
2834 window_id Unique window ID
2835 window_index #I Index of window
2836 window_last_flag 1 if window is the last used
2837 window_layout Window layout description, ignoring
2838 zoomed window panes
2839 window_linked 1 if window is linked across sessions
2840 window_linked_sessions Number of sessions this window is linked
2841 to
2842 window_linked_sessions_list List of sessions this window is linked to
2843 window_marked_flag 1 if window contains the marked pane
2844 window_name #W Name of window
2845 window_offset_x X offset into window if larger than
2846 client
2847 window_offset_y Y offset into window if larger than
2848 client
2849 window_panes Number of panes in window
2850 window_raw_flags Window flags with nothing escaped
2851 window_silence_flag 1 if window has silence alert
2852 window_stack_index Index in session most recent stack
2853 window_start_flag 1 if window has the lowest index
2854 window_visible_layout Window layout description, respecting
2855 zoomed window panes
2856 window_width Width of window
2857 window_zoomed_flag 1 if window is zoomed
2858 wrap_flag Pane wrap flag
2859
2861 tmux offers various options to specify the colour and attributes of as‐
2862 pects of the interface, for example status-style for the status line. In
2863 addition, embedded styles may be specified in format options, such as
2864 status-left, by enclosing them in ‘#[’ and ‘]’.
2865 A style may be the single term ‘default’ to specify the default style
2867 (which may come from an option, for example status-style in the status
2868 line) or a space or comma separated list of the following:
2869 fg=colour
2871 Set the foreground colour. The colour is one of: black, red,
2872 green, yellow, blue, magenta, cyan, white; if supported the
2873 bright variants brightred, brightgreen, brightyellow; colour0 to
2874 colour255 from the 256-colour set; default for the default
2875 colour; terminal for the terminal default colour; or a hexadeci‐
2876 mal RGB string such as ‘#ffffff’.
2877 bg=colour
2879 Set the background colour.
2880 none Set no attributes (turn off any active attributes).
2882 acs, bright (or bold), dim, underscore, blink, reverse, hidden, italics,
2884 overline, strikethrough, double-underscore, curly-underscore,
2885 dotted-underscore, dashed-underscore
2886 Set an attribute. Any of the attributes may be prefixed with
2887 ‘no’ to unset. acs is the terminal alternate character set.
2888 align=left (or noalign), align=centre, align=right
2890 Align text to the left, centre or right of the available space if
2891 appropriate.
2892 fill=colour
2894 Fill the available space with a background colour if appropriate.
2895 list=on, list=focus, list=left-marker, list=right-marker, nolist
2897 Mark the position of the various window list components in the
2898 status-format option: list=on marks the start of the list;
2899 list=focus is the part of the list that should be kept in focus
2900 if the entire list won't fit in the available space (typically
2901 the current window); list=left-marker and list=right-marker mark
2902 the text to be used to mark that text has been trimmed from the
2903 left or right of the list if there is not enough space.
2904 push-default, pop-default
2906 Store the current colours and attributes as the default or reset
2907 to the previous default. A push-default affects any subsequent
2908 use of the default term until a pop-default. Only one default
2909 may be pushed (each push-default replaces the previous saved de‐
2910 fault).
2911 range=left, range=right, range=window|X, norange
2913 Mark a range in the status-format option. range=left and
2914 range=right are the text used for the ‘StatusLeft’ and
2915 ‘StatusRight’ mouse keys. range=window|X is the range for a win‐
2916 dow passed to the ‘Status’ mouse key, where ‘X’ is a window in‐
2917 dex.
2918 Examples are:
2920 fg=yellow bold underscore blink
2922 bg=black,fg=default,noreverse
2923
2925 tmux distinguishes between names and titles. Windows and sessions have
2926 names, which may be used to specify them in targets and are displayed in
2927 the status line and various lists: the name is the tmux identifier for a
2928 window or session. Only panes have titles. A pane's title is typically
2929 set by the program running inside the pane using an escape sequence (like
2930 it would set the xterm(1) window title in X(7)). Windows themselves do
2931 not have titles - a window's title is the title of its active pane. tmux
2932 itself may set the title of the terminal in which the client is running,
2933 see the set-titles option.
2934 A session's name is set with the new-session and rename-session commands.
2936 A window's name is set with one of:
2937 1. A command argument (such as -n for new-window or new-session).
2939 2. An escape sequence (if the allow-rename option is turned on):
2941 $ printf '\033kWINDOW_NAME\033\\'
2943 3. Automatic renaming, which sets the name to the active command in
2945 the window's active pane. See the automatic-rename option.
2946 When a pane is first created, its title is the hostname. A pane's title
2948 can be set via the title setting escape sequence, for example:
2949 $ printf '\033]2;My Title\033\\'
2951 It can also be modified with the select-pane -T command.
2953
2955 When the server is started, tmux copies the environment into the global
2956 environment; in addition, each session has a session environment. When a
2957 window is created, the session and global environments are merged. If a
2958 variable exists in both, the value from the session environment is used.
2959 The result is the initial environment passed to the new process.
2960 The update-environment session option may be used to update the session
2962 environment from the client when a new session is created or an old reat‐
2963 tached. tmux also initialises the TMUX variable with some internal in‐
2964 formation to allow commands to be executed from inside, and the TERM
2965 variable with the correct terminal setting of ‘screen’.
2966 Variables in both session and global environments may be marked as hid‐
2968 den. Hidden variables are not passed into the environment of new pro‐
2969 cesses and instead can only be used by tmux itself (for example in for‐
2970 mats, see the FORMATS section).
2971 Commands to alter and view the environment are:
2973 set-environment [-Fhgru] [-t target-session] name [value]
2975 (alias: setenv)
2976 Set or unset an environment variable. If -g is used, the change
2977 is made in the global environment; otherwise, it is applied to
2978 the session environment for target-session. If -F is present,
2979 then value is expanded as a format. The -u flag unsets a vari‐
2980 able. -r indicates the variable is to be removed from the envi‐
2981 ronment before starting a new process. -h marks the variable as
2982 hidden.
2983 show-environment [-hgs] [-t target-session] [variable]
2985 (alias: showenv)
2986 Display the environment for target-session or the global environ‐
2987 ment with -g. If variable is omitted, all variables are shown.
2988 Variables removed from the environment are prefixed with ‘-’. If
2989 -s is used, the output is formatted as a set of Bourne shell com‐
2990 mands. -h shows hidden variables (omitted by default).
2991
2993 tmux includes an optional status line which is displayed in the bottom
2994 line of each terminal.
2995 By default, the status line is enabled and one line in height (it may be
2997 disabled or made multiple lines with the status session option) and con‐
2998 tains, from left-to-right: the name of the current session in square
2999 brackets; the window list; the title of the active pane in double quotes;
3000 and the time and date.
3001 Each line of the status line is configured with the status-format option.
3003 The default is made of three parts: configurable left and right sections
3004 (which may contain dynamic content such as the time or output from a
3005 shell command, see the status-left, status-left-length, status-right, and
3006 status-right-length options below), and a central window list. By de‐
3007 fault, the window list shows the index, name and (if any) flag of the
3008 windows present in the current session in ascending numerical order. It
3009 may be customised with the window-status-format and
3010 window-status-current-format options. The flag is one of the following
3011 symbols appended to the window name:
3012 Symbol Meaning
3014 * Denotes the current window.
3015 - Marks the last window (previously selected).
3016 # Window activity is monitored and activity has been
3017 detected.
3018 ! Window bells are monitored and a bell has occurred in the
3019 window.
3020 ~ The window has been silent for the monitor-silence
3021 interval.
3022 M The window contains the marked pane.
3023 Z The window's active pane is zoomed.
3024 The # symbol relates to the monitor-activity window option. The window
3026 name is printed in inverted colours if an alert (bell, activity or si‐
3027 lence) is present.
3028 The colour and attributes of the status line may be configured, the en‐
3030 tire status line using the status-style session option and individual
3031 windows using the window-status-style window option.
3032 The status line is automatically refreshed at interval if it has changed,
3034 the interval may be controlled with the status-interval session option.
3035 Commands related to the status line are as follows:
3037 clear-prompt-history [-T prompt-type]
3039 (alias: clearphist)
3040 Clear status prompt history for prompt type prompt-type. If -T
3041 is omitted, then clear history for all types. See command-prompt
3042 for possible values for prompt-type.
3043 command-prompt [-1bFikN] [-I inputs] [-p prompts] [-t target-client] [-T
3045 prompt-type] [template]
3046 Open the command prompt in a client. This may be used from in‐
3047 side tmux to execute commands interactively.
3048 If template is specified, it is used as the command. With -F,
3050 template is expanded as a format.
3051 If present, -I is a comma-separated list of the initial text for
3053 each prompt. If -p is given, prompts is a comma-separated list
3054 of prompts which are displayed in order; otherwise a single
3055 prompt is displayed, constructed from template if it is present,
3056 or ‘:’ if not.
3057 Before the command is executed, the first occurrence of the
3059 string ‘%%’ and all occurrences of ‘%1’ are replaced by the re‐
3060 sponse to the first prompt, all ‘%2’ are replaced with the re‐
3061 sponse to the second prompt, and so on for further prompts. Up
3062 to nine prompt responses may be replaced (‘%1’ to ‘%9’). ‘%%%’
3063 is like ‘%%’ but any quotation marks are escaped.
3064 -1 makes the prompt only accept one key press, in this case the
3066 resulting input is a single character. -k is like -1 but the key
3067 press is translated to a key name. -N makes the prompt only ac‐
3068 cept numeric key presses. -i executes the command every time the
3069 prompt input changes instead of when the user exits the command
3070 prompt.
3071 -T tells tmux the prompt type. This affects what completions are
3073 offered when Tab is pressed. Available types are: ‘command’,
3074 ‘search’, ‘target’ and ‘window-target’.
3075 The following keys have a special meaning in the command prompt,
3077 depending on the value of the status-keys option:
3078 Function vi emacs
3080 Cancel command prompt q Escape
3081 Delete from cursor to start of word C-w
3082 Delete entire command d C-u
3083 Delete from cursor to end D C-k
3084 Execute command Enter Enter
3085 Get next command from history Down
3086 Get previous command from history Up
3087 Insert top paste buffer p C-y
3088 Look for completions Tab Tab
3089 Move cursor left h Left
3090 Move cursor right l Right
3091 Move cursor to end $ C-e
3092 Move cursor to next word w M-f
3093 Move cursor to previous word b M-b
3094 Move cursor to start 0 C-a
3095 Transpose characters C-t
3096 With -b, the prompt is shown in the background and the invoking
3098 client does not exit until it is dismissed.
3099 confirm-before [-b] [-p prompt] [-t target-client] command
3101 (alias: confirm)
3102 Ask for confirmation before executing command. If -p is given,
3103 prompt is the prompt to display; otherwise a prompt is construc‐
3104 ted from command. It may contain the special character sequences
3105 supported by the status-left option. With -b, the prompt is
3106 shown in the background and the invoking client does not exit un‐
3107 til it is dismissed.
3108 display-menu [-O] [-c target-client] [-t target-pane] [-T title] [-x
3110 position] [-y position] name key command ...
3111 (alias: menu)
3112 Display a menu on target-client. target-pane gives the target
3113 for any commands run from the menu.
3114 A menu is passed as a series of arguments: first the menu item
3116 name, second the key shortcut (or empty for none) and third the
3117 command to run when the menu item is chosen. The name and com‐
3118 mand are formats, see the FORMATS and STYLES sections. If the
3119 name begins with a hyphen (-), then the item is disabled (shown
3120 dim) and may not be chosen. The name may be empty for a separa‐
3121 tor line, in which case both the key and command should be omit‐
3122 ted.
3123 -T is a format for the menu title (see FORMATS).
3125 -x and -y give the position of the menu. Both may be a row or
3127 column number, or one of the following special values:
3128 Value Flag Meaning
3130 C Both The centre of the terminal
3131 R -x The right side of the terminal
3132 P Both The bottom left of the pane
3133 M Both The mouse position
3134 W Both The window position on the status line
3135 S -y The line above or below the status line
3136 Or a format, which is expanded including the following additional
3138 variables:
3139 Variable name Replaced with
3141 popup_centre_x Centered in the client
3142 popup_centre_y Centered in the client
3143 popup_height Height of menu or popup
3144 popup_mouse_bottom Bottom of at the mouse
3145 popup_mouse_centre_x Horizontal centre at the
3146 mouse
3147 popup_mouse_centre_y Vertical centre at the mouse
3148 popup_mouse_top Top at the mouse
3149 popup_mouse_x Mouse X position
3150 popup_mouse_y Mouse Y position
3151 popup_pane_bottom Bottom of the pane
3152 popup_pane_left Left of the pane
3153 popup_pane_right Right of the pane
3154 popup_pane_top Top of the pane
3155 popup_status_line_y Above or below the status
3156 line
3157 popup_width Width of menu or popup
3158 popup_window_status_line_x At the window position in
3159 status line
3160 popup_window_status_line_y At the status line showing
3161 the window
3162 Each menu consists of items followed by a key shortcut shown in
3164 brackets. If the menu is too large to fit on the terminal, it is
3165 not displayed. Pressing the key shortcut chooses the correspond‐
3166 ing item. If the mouse is enabled and the menu is opened from a
3167 mouse key binding, releasing the mouse button with an item se‐
3168 lected chooses that item and releasing the mouse button without
3169 an item selected closes the menu. -O changes this behaviour so
3170 that the menu does not close when the mouse button is released
3171 without an item selected the menu is not closed and a mouse but‐
3172 ton must be clicked to choose an item.
3173 The following keys are also available:
3175 Key Function
3177 Enter Choose selected item
3178 Up Select previous item
3179 Down Select next item
3180 q Exit menu
3181 display-message [-aINpv] [-c target-client] [-d delay] [-t target-pane]
3183 [message]
3184 (alias: display)
3185 Display a message. If -p is given, the output is printed to std‐
3186 out, otherwise it is displayed in the target-client status line
3187 for up to delay milliseconds. If delay is not given, the
3188 display-time option is used; a delay of zero waits for a key
3189 press. ‘N’ ignores key presses and closes only after the delay
3190 expires. The format of message is described in the FORMATS sec‐
3191 tion; information is taken from target-pane if -t is given, oth‐
3192 erwise the active pane.
3193 -v prints verbose logging as the format is parsed and -a lists
3195 the format variables and their values.
3196 -I forwards any input read from stdin to the empty pane given by
3198 target-pane.
3199 display-popup [-BCE] [-b border-lines] [-c target-client] [-d
3201 start-directory] [-e environment] [-h height] [-s style] [-S
3202 border-style] [-t target-pane] [-T title] [-w width] [-x
3203 position] [-y position] [shell-command]
3204 (alias: popup)
3205 Display a popup running shell-command on target-client. A popup
3206 is a rectangular box drawn over the top of any panes. Panes are
3207 not updated while a popup is present.
3208 -E closes the popup automatically when shell-command exits. Two
3210 -E closes the popup only if shell-command exited with success.
3211 -x and -y give the position of the popup, they have the same
3213 meaning as for the display-menu command. -w and -h give the
3214 width and height - both may be a percentage (followed by ‘%’).
3215 If omitted, half of the terminal size is used.
3216 -B does not surround the popup by a border.
3218 -b sets the type of border line for the popup. When -B is speci‐
3220 fied, the -b option is ignored. See popup-border-lines for pos‐
3221 sible values for border-lines.
3222 -s sets the style for the popup and -S sets the style for the
3224 popup border. For how to specify style, see the STYLES section.
3225 -e takes the form ‘VARIABLE=value’ and sets an environment vari‐
3227 able for the popup; it may be specified multiple times.
3228 -T is a format for the popup title (see FORMATS).
3230 The -C flag closes any popup on the client.
3232 show-prompt-history [-T prompt-type]
3234 (alias: showphist)
3235 Display status prompt history for prompt type prompt-type. If -T
3236 is omitted, then show history for all types. See command-prompt
3237 for possible values for prompt-type.
3238
3240 tmux maintains a set of named paste buffers. Each buffer may be either
3241 explicitly or automatically named. Explicitly named buffers are named
3242 when created with the set-buffer or load-buffer commands, or by renaming
3243 an automatically named buffer with set-buffer -n. Automatically named
3244 buffers are given a name such as ‘buffer0001’, ‘buffer0002’ and so on.
3245 When the buffer-limit option is reached, the oldest automatically named
3246 buffer is deleted. Explicitly named buffers are not subject to
3247 buffer-limit and may be deleted with the delete-buffer command.
3248 Buffers may be added using copy-mode or the set-buffer and load-buffer
3250 commands, and pasted into a window using the paste-buffer command. If a
3251 buffer command is used and no buffer is specified, the most recently
3252 added automatically named buffer is assumed.
3253 A configurable history buffer is also maintained for each window. By de‐
3255 fault, up to 2000 lines are kept; this can be altered with the
3256 history-limit option (see the set-option command above).
3257 The buffer commands are as follows:
3259 choose-buffer [-NZr] [-F format] [-f filter] [-K key-format] [-O
3261 sort-order] [-t target-pane] [template]
3262 Put a pane into buffer mode, where a buffer may be chosen inter‐
3263 actively from a list. Each buffer is shown on one line. A
3264 shortcut key is shown on the left in brackets allowing for imme‐
3265 diate choice, or the list may be navigated and an item chosen or
3266 otherwise manipulated using the keys below. -Z zooms the pane.
3267 The following keys may be used in buffer mode:
3268 Key Function
3270 Enter Paste selected buffer
3271 Up Select previous buffer
3272 Down Select next buffer
3273 C-s Search by name or content
3274 n Repeat last search
3275 t Toggle if buffer is tagged
3276 T Tag no buffers
3277 C-t Tag all buffers
3278 p Paste selected buffer
3279 P Paste tagged buffers
3280 d Delete selected buffer
3281 D Delete tagged buffers
3282 e Open the buffer in an editor
3283 f Enter a format to filter items
3284 O Change sort field
3285 r Reverse sort order
3286 v Toggle preview
3287 q Exit mode
3288 After a buffer is chosen, ‘%%’ is replaced by the buffer name in
3290 template and the result executed as a command. If template is
3291 not given, "paste-buffer -b '%%'" is used.
3292 -O specifies the initial sort field: one of ‘time’, ‘name’ or
3294 ‘size’. -r reverses the sort order. -f specifies an initial
3295 filter: the filter is a format - if it evaluates to zero, the
3296 item in the list is not shown, otherwise it is shown. If a fil‐
3297 ter would lead to an empty list, it is ignored. -F specifies the
3298 format for each item in the list and -K a format for each short‐
3299 cut key; both are evaluated once for each line. -N starts with‐
3300 out the preview. This command works only if at least one client
3301 is attached.
3302 clear-history [-t target-pane]
3304 (alias: clearhist)
3305 Remove and free the history for the specified pane.
3306 delete-buffer [-b buffer-name]
3308 (alias: deleteb)
3309 Delete the buffer named buffer-name, or the most recently added
3310 automatically named buffer if not specified.
3311 list-buffers [-F format] [-f filter]
3313 (alias: lsb)
3314 List the global buffers. -F specifies the format of each line
3315 and -f a filter. Only buffers for which the filter is true are
3316 shown. See the FORMATS section.
3317 load-buffer [-w] [-b buffer-name] [-t target-client] path
3319 (alias: loadb)
3320 Load the contents of the specified paste buffer from path. If -w
3321 is given, the buffer is also sent to the clipboard for
3322 target-client using the xterm(1) escape sequence, if possible.
3323 paste-buffer [-dpr] [-b buffer-name] [-s separator] [-t target-pane]
3325 (alias: pasteb)
3326 Insert the contents of a paste buffer into the specified pane.
3327 If not specified, paste into the current one. With -d, also
3328 delete the paste buffer. When output, any linefeed (LF) charac‐
3329 ters in the paste buffer are replaced with a separator, by de‐
3330 fault carriage return (CR). A custom separator may be specified
3331 using the -s flag. The -r flag means to do no replacement
3332 (equivalent to a separator of LF). If -p is specified, paste
3333 bracket control codes are inserted around the buffer if the ap‐
3334 plication has requested bracketed paste mode.
3335 save-buffer [-a] [-b buffer-name] path
3337 (alias: saveb)
3338 Save the contents of the specified paste buffer to path. The -a
3339 option appends to rather than overwriting the file.
3340 set-buffer [-aw] [-b buffer-name] [-t target-client] [-n new-buffer-name]
3342 data
3343 (alias: setb)
3344 Set the contents of the specified buffer to data. If -w is
3345 given, the buffer is also sent to the clipboard for target-client
3346 using the xterm(1) escape sequence, if possible. The -a option
3347 appends to rather than overwriting the buffer. The -n option re‐
3348 names the buffer to new-buffer-name.
3349 show-buffer [-b buffer-name]
3351 (alias: showb)
3352 Display the contents of the specified buffer.
3353
3355 Miscellaneous commands are as follows:
3356 clock-mode [-t target-pane]
3358 Display a large clock.
3359 if-shell [-bF] [-t target-pane] shell-command command [command]
3361 (alias: if)
3362 Execute the first command if shell-command (run with /bin/sh) re‐
3363 turns success or the second command otherwise. Before being exe‐
3364 cuted, shell-command is expanded using the rules specified in the
3365 FORMATS section, including those relevant to target-pane. With
3366 -b, shell-command is run in the background.
3367 If -F is given, shell-command is not executed but considered suc‐
3369 cess if neither empty nor zero (after formats are expanded).
3370 lock-server
3372 (alias: lock)
3373 Lock each client individually by running the command specified by
3374 the lock-command option.
3375 run-shell [-bC] [-d delay] [-t target-pane] [shell-command]
3377 (alias: run)
3378 Execute shell-command using /bin/sh or (with -C) a tmux command
3379 in the background without creating a window. Before being exe‐
3380 cuted, shell-command is expanded using the rules specified in the
3381 FORMATS section. With -b, the command is run in the background.
3382 -d waits for delay seconds before starting the command. If -C is
3383 not given, any output to stdout is displayed in view mode (in the
3384 pane specified by -t or the current pane if omitted) after the
3385 command finishes. If the command fails, the exit status is also
3386 displayed.
3387 wait-for [-L | -S | -U] channel
3389 (alias: wait)
3390 When used without options, prevents the client from exiting until
3391 woken using wait-for -S with the same channel. When -L is used,
3392 the channel is locked and any clients that try to lock the same
3393 channel are made to wait until the channel is unlocked with
3394 wait-for -U.
3395
3397 When a tmux client detaches, it prints a message. This may be one of:
3398 detached (from session ...)
3400 The client was detached normally.
3401 detached and SIGHUP
3403 The client was detached and its parent sent the SIGHUP signal
3404 (for example with detach-client -P).
3405 lost tty
3407 The client's tty(4) or pty(4) was unexpectedly destroyed.
3408 terminated
3410 The client was killed with SIGTERM.
3411 too far behind
3413 The client is in control mode and became unable to keep up with
3414 the data from tmux.
3415 exited The server exited when it had no sessions.
3417 server exited
3419 The server exited when it received SIGTERM.
3420 server exited unexpectedly
3422 The server crashed or otherwise exited without telling the client
3423 the reason.
3424
3426 tmux understands some unofficial extensions to terminfo(5). It is not
3427 normally necessary to set these manually, instead the terminal-features
3428 option should be used.
3429 AX An existing extension that tells tmux the terminal supports de‐
3431 fault colours.
3432 Bidi Tell tmux that the terminal supports the VTE bidirectional text
3434 extensions.
3435 Cs, Cr Set the cursor colour. The first takes a single string argument
3437 and is used to set the colour; the second takes no arguments and
3438 restores the default cursor colour. If set, a sequence such as
3439 this may be used to change the cursor colour from inside tmux:
3440 $ printf '\033]12;red\033\\'
3442 The colour is an X(7) colour, see XParseColor(3).
3444 Cmg, Clmg, Dsmg, Enmg
3446 Set, clear, disable or enable DECSLRM margins. These are set au‐
3447 tomatically if the terminal reports it is VT420 compatible.
3448 Dsbp, Enbp
3450 Disable and enable bracketed paste. These are set automatically
3451 if the XT capability is present.
3452 Dseks, Eneks
3454 Disable and enable extended keys.
3455 Dsfcs, Enfcs
3457 Disable and enable focus reporting. These are set automatically
3458 if the XT capability is present.
3459 Rect Tell tmux that the terminal supports rectangle operations.
3461 Smol Enable the overline attribute.
3463 Smulx Set a styled underscore. The single parameter is one of: 0 for
3465 no underscore, 1 for normal underscore, 2 for double underscore,
3466 3 for curly underscore, 4 for dotted underscore and 5 for dashed
3467 underscore.
3468 Setulc, ol
3470 Set the underscore colour or reset to the default. The argument
3471 is (red * 65536) + (green * 256) + blue where each is between 0
3472 and 255.
3473 Ss, Se Set or reset the cursor style. If set, a sequence such as this
3475 may be used to change the cursor to an underline:
3476 $ printf '\033[4 q'
3478 If Se is not set, Ss with argument 0 will be used to reset the
3480 cursor style instead.
3481 Swd Set the opening sequence for the working directory notification.
3483 The sequence is terminated using the standard fsl capability.
3484 Sync Start (parameter is 1) or end (parameter is 2) a synchronized up‐
3486 date.
3487 Tc Indicate that the terminal supports the ‘direct colour’ RGB es‐
3489 cape sequence (for example, \e[38;2;255;255;255m).
3490 If supported, this is used for the initialize colour escape se‐
3492 quence (which may be enabled by adding the ‘initc’ and ‘ccc’ ca‐
3493 pabilities to the tmux [22mterminfo(5) entry).
3494 This is equivalent to the RGB terminfo(5) capability.
3496 Ms Store the current buffer in the host terminal's selection (clip‐
3498 board). See the set-clipboard option above and the xterm(1) man
3499 page.
3500 XT This is an existing extension capability that tmux uses to mean
3502 that the terminal supports the xterm(1) title set sequences and
3503 to automatically set some of the capabilities above.
3504
3506 tmux offers a textual interface called control mode. This allows appli‐
3507 cations to communicate with tmux using a simple text-only protocol.
3508 In control mode, a client sends tmux commands or command sequences termi‐
3510 nated by newlines on standard input. Each command will produce one block
3511 of output on standard output. An output block consists of a %begin line
3512 followed by the output (which may be empty). The output block ends with
3513 a %end or %error. %begin and matching %end or %error have three argu‐
3514 ments: an integer time (as seconds from epoch), command number and flags
3515 (currently not used). For example:
3516 %begin 1363006971 2 1
3518 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
3519 %end 1363006971 2 1
3520 The refresh-client -C command may be used to set the size of a client in
3522 control mode.
3523 In control mode, tmux outputs notifications. A notification will never
3525 occur inside an output block.
3526 The following notifications are defined:
3528 %client-detached client
3530 The client has detached.
3531 %client-session-changed client session-id name
3533 The client is now attached to the session with ID session-id,
3534 which is named name.
3535 %continue pane-id
3537 The pane has been continued after being paused (if the
3538 pause-after flag is set, see refresh-client -A).
3539 %exit [reason]
3541 The tmux client is exiting immediately, either because it is not
3542 attached to any session or an error occurred. If present, reason
3543 describes why the client exited.
3544 %extended-output pane-id age ... : value
3546 New form of %output sent when the pause-after flag is set. age
3547 is the time in milliseconds for which tmux had buffered the out‐
3548 put before it was sent. Any subsequent arguments up until a sin‐
3549 gle ‘:’ are for future use and should be ignored.
3550 %layout-change window-id window-layout window-visible-layout window-flags
3552 The layout of a window with ID window-id changed. The new layout
3553 is window-layout. The window's visible layout is
3554 window-visible-layout and the window flags are window-flags.
3555 %output pane-id value
3557 A window pane produced output. value escapes non-printable char‐
3558 acters and backslash as octal \xxx.
3559 %pane-mode-changed pane-id
3561 The pane with ID pane-id has changed mode.
3562 %pause pane-id
3564 The pane has been paused (if the pause-after flag is set).
3565 %session-changed session-id name
3567 The client is now attached to the session with ID session-id,
3568 which is named name.
3569 %session-renamed name
3571 The current session was renamed to name.
3572 %session-window-changed session-id window-id
3574 The session with ID session-id changed its active window to the
3575 window with ID window-id.
3576 %sessions-changed
3578 A session was created or destroyed.
3579 %subscription-changed name session-id window-id window-index pane-id ...
3581 : value
3582 The value of the format associated with subscription name has
3583 changed to value. See refresh-client -B. Any arguments after
3584 pane-id up until a single ‘:’ are for future use and should be
3585 ignored.
3586 %unlinked-window-add window-id
3588 The window with ID window-id was created but is not linked to the
3589 current session.
3590 %unlinked-window-close window-id
3592 The window with ID window-id, which is not linked to the current
3593 session, was closed.
3594 %unlinked-window-renamed window-id
3596 The window with ID window-id, which is not linked to the current
3597 session, was renamed.
3598 %window-add window-id
3600 The window with ID window-id was linked to the current session.
3601 %window-close window-id
3603 The window with ID window-id closed.
3604 %window-pane-changed window-id pane-id
3606 The active pane in the window with ID window-id changed to the
3607 pane with ID pane-id.
3608 %window-renamed window-id name
3610 The window with ID window-id was renamed to name.
3611
3613 When tmux is started, it inspects the following environment variables:
3614 EDITOR If the command specified in this variable contains the string
3616 ‘vi’ and VISUAL is unset, use vi-style key bindings. Overrid‐
3617 den by the mode-keys and status-keys options.
3618 HOME The user's login directory. If unset, the passwd(5) database
3620 is consulted.
3621 LC_CTYPE The character encoding locale(1). It is used for two separate
3623 purposes. For output to the terminal, UTF-8 is used if the -u
3624 option is given or if LC_CTYPE contains "UTF-8" or "UTF8".
3625 Otherwise, only ASCII characters are written and non-ASCII
3626 characters are replaced with underscores (‘_’). For input,
3627 tmux always runs with a UTF-8 locale. If en_US.UTF-8 is pro‐
3628 vided by the operating system, it is used and LC_CTYPE is ig‐
3629 nored for input. Otherwise, LC_CTYPE tells tmux what the UTF-8
3630 locale is called on the current system. If the locale speci‐
3631 fied by LC_CTYPE is not available or is not a UTF-8 locale,
3632 tmux exits with an error message.
3633 LC_TIME The date and time format locale(1). It is used for locale-de‐
3635 pendent strftime(3) format specifiers.
3636 PWD The current working directory to be set in the global environ‐
3638 ment. This may be useful if it contains symbolic links. If
3639 the value of the variable does not match the current working
3640 directory, the variable is ignored and the result of getcwd(3)
3641 is used instead.
3642 SHELL The absolute path to the default shell for new windows. See
3644 the default-shell option for details.
3645 TMUX_TMPDIR
3647 The parent directory of the directory containing the server
3648 sockets. See the -L option for details.
3649 VISUAL If the command specified in this variable contains the string
3651 ‘vi’, use vi-style key bindings. Overridden by the mode-keys
3652 and status-keys options.
3653
3655 ~/.tmux.conf
3656 $XDG_CONFIG_HOME/tmux/tmux.conf
3657 ~/.config/tmux/tmux.conf
3658 Default tmux configuration file.
3659 /etc/tmux.conf System-wide configuration file.
3660
3662 To create a new tmux session running vi(1):
3663 $ tmux new-session vi
3665 Most commands have a shorter form, known as an alias. For new-session,
3667 this is new:
3668 $ tmux new vi
3670 Alternatively, the shortest unambiguous form of a command is accepted.
3672 If there are several options, they are listed:
3673 $ tmux n
3675 ambiguous command: n, could be: new-session, new-window, next-window
3676 Within an active session, a new window may be created by typing ‘C-b c’
3678 (Ctrl followed by the ‘b’ key followed by the ‘c’ key).
3679 Windows may be navigated with: ‘C-b 0’ (to select window 0), ‘C-b 1’ (to
3681 select window 1), and so on; ‘C-b n’ to select the next window; and ‘C-b
3682 p’ to select the previous window.
3683 A session may be detached using ‘C-b d’ (or by an external event such as
3685 ssh(1) disconnection) and reattached with:
3686 $ tmux attach-session
3688 Typing ‘C-b ?’ lists the current key bindings in the current window; up
3690 and down may be used to navigate the list or ‘q’ to exit from it.
3691 Commands to be run when the tmux server is started may be placed in the
3693 ~/.tmux.conf configuration file. Common examples include:
3694 Changing the default prefix key:
3696 set-option -g prefix C-a
3698 unbind-key C-b
3699 bind-key C-a send-prefix
3700 Turning the status line off, or changing its colour:
3702 set-option -g status off
3704 set-option -g status-style bg=blue
3705 Setting other options, such as the default command, or locking after 30
3707 minutes of inactivity:
3708 set-option -g default-command "exec /bin/ksh"
3710 set-option -g lock-after-time 1800
3711 Creating new key bindings:
3713 bind-key b set-option status
3715 bind-key / command-prompt "split-window 'exec man %%'"
3716 bind-key S command-prompt "new-window -n %1 'ssh %1'"
3717
3719 pty(4)
3720
3722 Nicholas Marriott <nicholas.marriott@gmail.com>
3723BSD February 8, 2023 BSD