1TMUX(1) BSD General Commands Manual TMUX(1)
2
4 tmux — terminal multiplexer
5
7 tmux [-2CluvV] [-c shell-command] [-f file] [-L socket-name]
8 [-S socket-path] [command [flags]]
9
11 tmux is a terminal multiplexer: it enables a number of terminals to be
12 created, accessed, and controlled from a single screen. tmux may be
13 detached from a screen and continue running in the background, then later
14 reattached.
15 When tmux is started it creates a new session with a single window and
17 displays it on screen. A status line at the bottom of the screen shows
18 information on the current session and is used to enter interactive com‐
19 mands.
20 A session is a single collection of pseudo terminals under the management
22 of tmux. Each session has one or more windows linked to it. A window
23 occupies the entire screen and may be split into rectangular panes, each
24 of which is a separate pseudo terminal (the pty(4) manual page documents
25 the technical details of pseudo terminals). Any number of tmux instances
26 may connect to the same session, and any number of windows may be present
27 in the same session. Once all sessions are killed, tmux exits.
28 Each session is persistent and will survive accidental disconnection
30 (such as ssh(1) connection timeout) or intentional detaching (with the
31 ‘C-b d’ key strokes). tmux may be reattached using:
32 $ tmux attach
34 In tmux, a session is displayed on screen by a client and all sessions
36 are managed by a single server. The server and each client are separate
37 processes which communicate through a socket in /tmp.
38 The options are as follows:
40 -2 Force tmux to assume the terminal supports 256 colours.
42 -C Start in control mode (see the CONTROL MODE section).
44 Given twice (-CC) disables echo.
45 -c shell-command
47 Execute shell-command using the default shell. If neces‐
48 sary, the tmux server will be started to retrieve the
49 default-shell option. This option is for compatibility
50 with sh(1) when tmux is used as a login shell.
51 -f file Specify an alternative configuration file. By default,
53 tmux loads the system configuration file from
54 /etc/tmux.conf, if present, then looks for a user configu‐
55 ration file at ~/.tmux.conf.
56 The configuration file is a set of tmux commands which are
58 executed in sequence when the server is first started.
59 tmux loads configuration files once when the server process
60 has started. The source-file command may be used to load a
61 file later.
62 tmux shows any error messages from commands in configura‐
64 tion files in the first session created, and continues to
65 process the rest of the configuration file.
66 -L socket-name
68 tmux stores the server socket in a directory under
69 TMUX_TMPDIR or /tmp if it is unset. The default socket is
70 named default. This option allows a different socket name
71 to be specified, allowing several independent tmux servers
72 to be run. Unlike -S a full path is not necessary: the
73 sockets are all created in the same directory.
74 If the socket is accidentally removed, the SIGUSR1 signal
76 may be sent to the tmux server process to recreate it (note
77 that this will fail if any parent directories are missing).
78 -l Behave as a login shell. This flag currently has no effect
80 and is for compatibility with other shells when using tmux
81 as a login shell.
82 -S socket-path
84 Specify a full alternative path to the server socket. If
85 -S is specified, the default socket directory is not used
86 and any -L flag is ignored.
87 -u When starting, tmux looks for the LC_ALL, LC_CTYPE and LANG
89 environment variables: if the first found contains ‘UTF-8’,
90 then the terminal is assumed to support UTF-8. This is not
91 always correct: the -u flag explicitly informs tmux that
92 UTF-8 is supported.
93 Note that tmux itself always accepts UTF-8; this controls
95 whether it will send UTF-8 characters to the terminal it is
96 running (if not, they are replaced by ‘_’).
97 -v Request verbose logging. Log messages will be saved into
99 tmux-client-PID.log and tmux-server-PID.log files in the
100 current directory, where PID is the PID of the server or
101 client process. If -v is specified twice, an additional
102 tmux-out-PID.log file is generated with a copy of every‐
103 thing tmux writes to the terminal.
104 The SIGUSR2 signal may be sent to the tmux server process
106 to toggle logging between on (as if -v was given) and off.
107 -V Report the tmux version.
109 command [flags]
111 This specifies one of a set of commands used to control
112 tmux, as described in the following sections. If no com‐
113 mands are specified, the new-session command is assumed.
114
116 tmux may be controlled from an attached client by using a key combination
117 of a prefix key, ‘C-b’ (Ctrl-b) by default, followed by a command key.
118 The default command key bindings are:
120 C-b Send the prefix key (C-b) through to the application.
122 C-o Rotate the panes in the current window forwards.
123 C-z Suspend the tmux client.
124 ! Break the current pane out of the window.
125 " Split the current pane into two, top and bottom.
126 # List all paste buffers.
127 $ Rename the current session.
128 % Split the current pane into two, left and right.
129 & Kill the current window.
130 ' Prompt for a window index to select.
131 ( Switch the attached client to the previous session.
132 ) Switch the attached client to the next session.
133 , Rename the current window.
134 - Delete the most recently copied buffer of text.
135 . Prompt for an index to move the current window.
136 0 to 9 Select windows 0 to 9.
137 : Enter the tmux command prompt.
138 ; Move to the previously active pane.
139 = Choose which buffer to paste interactively from a list.
140 ? List all key bindings.
141 D Choose a client to detach.
142 L Switch the attached client back to the last session.
143 [ Enter copy mode to copy text or view the history.
144 ] Paste the most recently copied buffer of text.
145 c Create a new window.
146 d Detach the current client.
147 f Prompt to search for text in open windows.
148 i Display some information about the current window.
149 l Move to the previously selected window.
150 n Change to the next window.
151 o Select the next pane in the current window.
152 p Change to the previous window.
153 q Briefly display pane indexes.
154 r Force redraw of the attached client.
155 m Mark the current pane (see select-pane -m).
156 M Clear the marked pane.
157 s Select a new session for the attached client interac‐
158 tively.
159 t Show the time.
160 w Choose the current window interactively.
161 x Kill the current pane.
162 z Toggle zoom state of the current pane.
163 { Swap the current pane with the previous pane.
164 } Swap the current pane with the next pane.
165 ~ Show previous messages from tmux, if any.
166 Page Up Enter copy mode and scroll one page up.
167 Up, Down
168 Left, Right
169 Change to the pane above, below, to the left, or to the
170 right of the current pane.
171 M-1 to M-5 Arrange panes in one of the five preset layouts: even-
172 horizontal, even-vertical, main-horizontal, main-verti‐
173 cal, or tiled.
174 Space Arrange the current window in the next preset layout.
175 M-n Move to the next window with a bell or activity marker.
176 M-o Rotate the panes in the current window backwards.
177 M-p Move to the previous window with a bell or activity
178 marker.
179 C-Up, C-Down
180 C-Left, C-Right
181 Resize the current pane in steps of one cell.
182 M-Up, M-Down
183 M-Left, M-Right
184 Resize the current pane in steps of five cells.
185 Key bindings may be changed with the bind-key and unbind-key commands.
187
189 This section contains a list of the commands supported by tmux. Most
190 commands accept the optional -t (and sometimes -s) argument with one of
191 target-client, target-session target-window, or target-pane. These spec‐
192 ify the client, session, window or pane which a command should affect.
193 target-client should be the name of the client, typically the pty(4) file
195 to which the client is connected, for example either of /dev/ttyp1 or
196 ttyp1 for the client attached to /dev/ttyp1. If no client is specified,
197 tmux attempts to work out the client currently in use; if that fails, an
198 error is reported. Clients may be listed with the list-clients command.
199 target-session is tried as, in order:
201 1. A session ID prefixed with a $.
203 2. An exact name of a session (as listed by the list-sessions
205 command).
206 3. The start of a session name, for example ‘mysess’ would match
208 a session named ‘mysession’.
209 4. An fnmatch(3) pattern which is matched against the session
211 name.
212 If the session name is prefixed with an ‘=’, only an exact match is
214 accepted (so ‘=mysess’ will only match exactly ‘mysess’, not
215 ‘mysession’).
216 If a single session is found, it is used as the target session; multiple
218 matches produce an error. If a session is omitted, the current session
219 is used if available; if no current session is available, the most
220 recently used is chosen.
221 target-window (or src-window or dst-window) specifies a window in the
223 form session:window. session follows the same rules as for
224 target-session, and window is looked for in order as:
225 1. A special token, listed below.
227 2. A window index, for example ‘mysession:1’ is window 1 in ses‐
229 sion ‘mysession’.
230 3. A window ID, such as @1.
232 4. An exact window name, such as ‘mysession:mywindow’.
234 5. The start of a window name, such as ‘mysession:mywin’.
236 6. As an fnmatch(3) pattern matched against the window name.
238 Like sessions, a ‘=’ prefix will do an exact match only. An empty window
240 name specifies the next unused index if appropriate (for example the
241 new-window and link-window commands) otherwise the current window in
242 session is chosen.
243 The following special tokens are available to indicate particular win‐
245 dows. Each has a single-character alternative form.
246 Token Meaning
248 {start} ^ The lowest-numbered window
249 {end} $ The highest-numbered window
250 {last} ! The last (previously current) window
251 {next} + The next window by number
252 {previous} - The previous window by number
253 target-pane (or src-pane or dst-pane) may be a pane ID or takes a similar
255 form to target-window but with the optional addition of a period followed
256 by a pane index or pane ID, for example: ‘mysession:mywindow.1’. If the
257 pane index is omitted, the currently active pane in the specified window
258 is used. The following special tokens are available for the pane index:
259 Token Meaning
261 {last} ! The last (previously active) pane
262 {next} + The next pane by number
263 {previous} - The previous pane by number
264 {top} The top pane
265 {bottom} The bottom pane
266 {left} The leftmost pane
267 {right} The rightmost pane
268 {top-left} The top-left pane
269 {top-right} The top-right pane
270 {bottom-left} The bottom-left pane
271 {bottom-right} The bottom-right pane
272 {up-of} The pane above the active pane
273 {down-of} The pane below the active pane
274 {left-of} The pane to the left of the active pane
275 {right-of} The pane to the right of the active pane
276 The tokens ‘+’ and ‘-’ may be followed by an offset, for example:
278 select-window -t:+2
280 In addition, target-session, target-window or target-pane may consist
282 entirely of the token ‘{mouse}’ (alternative form ‘=’) to specify the
283 most recent mouse event (see the MOUSE SUPPORT section) or ‘{marked}’
284 (alternative form ‘~’) to specify the marked pane (see select-pane -m).
285 Sessions, window and panes are each numbered with a unique ID; session
287 IDs are prefixed with a ‘$’, windows with a ‘@’, and panes with a ‘%’.
288 These are unique and are unchanged for the life of the session, window or
289 pane in the tmux server. The pane ID is passed to the child process of
290 the pane in the TMUX_PANE environment variable. IDs may be displayed
291 using the ‘session_id’, ‘window_id’, or ‘pane_id’ formats (see the
292 FORMATS section) and the display-message, list-sessions, list-windows or
293 list-panes commands.
294 shell-command arguments are sh(1) commands. This may be a single argu‐
296 ment passed to the shell, for example:
297 new-window 'vi /etc/passwd'
299 Will run:
301 /bin/sh -c 'vi /etc/passwd'
303 Additionally, the new-window, new-session, split-window, respawn-window
305 and respawn-pane commands allow shell-command to be given as multiple
306 arguments and executed directly (without ‘sh -c’). This can avoid issues
307 with shell quoting. For example:
308 $ tmux new-window vi /etc/passwd
310 Will run vi(1) directly without invoking the shell.
312 command [arguments] refers to a tmux command, passed with the command and
314 arguments separately, for example:
315 bind-key F1 set-option status off
317 Or if using sh(1):
319 $ tmux bind-key F1 set-option status off
321 Multiple commands may be specified together as part of a command
323 sequence. Each command should be separated by spaces and a semicolon;
324 commands are executed sequentially from left to right and lines ending
325 with a backslash continue on to the next line, except when escaped by
326 another backslash. A literal semicolon may be included by escaping it
327 with a backslash (for example, when specifying a command sequence to
328 bind-key).
329 Example tmux commands include:
331 refresh-client -t/dev/ttyp2
333 rename-session -tfirst newname
335 set-window-option -t:0 monitor-activity on
337 new-window ; split-window -d
339 bind-key R source-file ~/.tmux.conf \; \
341 display-message "source-file done"
342 Or from sh(1):
344 $ tmux kill-window -t :1
346 $ tmux new-window \; split-window -d
348 $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach
350
352 The tmux server manages clients, sessions, windows and panes. Clients
353 are attached to sessions to interact with them, either when they are cre‐
354 ated with the new-session command, or later with the attach-session com‐
355 mand. Each session has one or more windows linked into it. Windows may
356 be linked to multiple sessions and are made up of one or more panes, each
357 of which contains a pseudo terminal. Commands for creating, linking and
358 otherwise manipulating windows are covered in the WINDOWS AND PANES sec‐
359 tion.
360 The following commands are available to manage clients and sessions:
362 attach-session [-dEr] [-c working-directory] [-t target-session]
364 (alias: attach)
365 If run from outside tmux, create a new client in the current ter‐
366 minal and attach it to target-session. If used from inside,
367 switch the current client. If -d is specified, any other clients
368 attached to the session are detached. -r signifies the client is
369 read-only (only keys bound to the detach-client or switch-client
370 commands have any effect)
371 If no server is started, attach-session will attempt to start it;
373 this will fail unless sessions are created in the configuration
374 file.
375 The target-session rules for attach-session are slightly
377 adjusted: if tmux needs to select the most recently used session,
378 it will prefer the most recently used unattached session.
379 -c will set the session working directory (used for new windows)
381 to working-directory.
382 If -E is used, the update-environment option will not be applied.
384 detach-client [-aP] [-E shell-command] [-s target-session] [-t
386 target-client]
387 (alias: detach)
388 Detach the current client if bound to a key, the client specified
389 with -t, or all clients currently attached to the session speci‐
390 fied by -s. The -a option kills all but the client given with
391 -t. If -P is given, send SIGHUP to the parent process of the
392 client, typically causing it to exit. With -E, run shell-command
393 to replace the client.
394 has-session [-t target-session]
396 (alias: has)
397 Report an error and exit with 1 if the specified session does not
398 exist. If it does exist, exit with 0.
399 kill-server
401 Kill the tmux server and clients and destroy all sessions.
402 kill-session [-aC] [-t target-session]
404 Destroy the given session, closing any windows linked to it and
405 no other sessions, and detaching all clients attached to it. If
406 -a is given, all sessions but the specified one is killed. The
407 -C flag clears alerts (bell, activity, or silence) in all windows
408 linked to the session.
409 list-clients [-F format] [-t target-session]
411 (alias: lsc)
412 List all clients attached to the server. For the meaning of the
413 -F flag, see the FORMATS section. If target-session is speci‐
414 fied, list only clients connected to that session.
415 list-commands [-F format]
417 (alias: lscm)
418 List the syntax of all commands supported by tmux.
419 list-sessions [-F format]
421 (alias: ls)
422 List all sessions managed by the server. For the meaning of the
423 -F flag, see the FORMATS section.
424 lock-client [-t target-client]
426 (alias: lockc)
427 Lock target-client, see the lock-server command.
428 lock-session [-t target-session]
430 (alias: locks)
431 Lock all clients attached to target-session.
432 new-session [-AdDEP] [-c start-directory] [-F format] [-n window-name]
434 [-s session-name] [-t group-name] [-x width] [-y height]
435 [shell-command]
436 (alias: new)
437 Create a new session with name session-name.
438 The new session is attached to the current terminal unless -d is
440 given. window-name and shell-command are the name of and shell
441 command to execute in the initial window. With -d, the initial
442 size comes from the global default-size option; -x and -y can be
443 used to specify a different size. ‘-’ uses the size of the cur‐
444 rent client if any. If -x or -y is given, the default-size
445 option is set for the session.
446 If run from a terminal, any termios(4) special characters are
448 saved and used for new windows in the new session.
449 The -A flag makes new-session behave like attach-session if
451 session-name already exists; in this case, -D behaves like -d to
452 attach-session.
453 If -t is given, it specifies a session group. Sessions in the
455 same group share the same set of windows - new windows are linked
456 to all sessions in the group and any windows closed removed from
457 all sessions. The current and previous window and any session
458 options remain independent and any session in a group may be
459 killed without affecting the others. The group-name argument may
460 be:
461 1. the name of an existing group, in which case the new ses‐
463 sion is added to that group;
464 2. the name of an existing session - the new session is
466 added to the same group as that session, creating a new
467 group if necessary;
468 3. the name for a new group containing only the new session.
470 -n and shell-command are invalid if -t is used.
472 The -P option prints information about the new session after it
474 has been created. By default, it uses the format
475 ‘#{session_name}:’ but a different format may be specified with
476 -F.
477 If -E is used, the update-environment option will not be applied.
479 refresh-client [-cDlLRSU] [-C width,height] [-t target-client]
481 [adjustment]
482 (alias: refresh)
483 Refresh the current client if bound to a key, or a single client
484 if one is given with -t. If -S is specified, only update the
485 client's status line.
486 The -U, -D, -L -R, and -c flags allow the visible portion of a
488 window which is larger than the client to be changed. -U moves
489 the visible part up by adjustment rows and -D down, -L left by
490 adjustment columns and -R right. -c returns to tracking the cur‐
491 sor automatically. If adjustment is omitted, 1 is used. Note
492 that the visible position is a property of the client not of the
493 window, changing the current window in the attached session will
494 reset it.
495 -C sets the width and height of a control client. -l requests
497 the clipboard from the client using the xterm(1) escape sequence
498 and stores it in a new paste buffer.
499 -L, -R, -U and -D move the visible portion of the window left,
501 right, up or down by adjustment, if the window is larger than the
502 client. -c resets so that the position follows the cursor. See
503 the window-size option.
504 rename-session [-t target-session] new-name
506 (alias: rename)
507 Rename the session to new-name.
508 show-messages [-JT] [-t target-client]
510 (alias: showmsgs)
511 Show client messages or server information. Any messages dis‐
512 played on the status line are saved in a per-client message log,
513 up to a maximum of the limit set by the message-limit server
514 option. With -t, display the log for target-client. -J and -T
515 show debugging information about jobs and terminals.
516 source-file [-q] path
518 (alias: source)
519 Execute commands from path (which may be a glob(7) pattern). If
520 -q is given, no error will be returned if path does not exist.
521 Within a configuration file, commands may be made conditional by
523 surrounding them with %if and %endif lines. Additional %elif and
524 %else lines may also be used. The argument to %if and %elif is
525 expanded as a format and if it evaluates to false (zero or
526 empty), subsequent lines are ignored until the next %elif, %else
527 or %endif. For example:
528 %if #{==:#{host},myhost}
530 set -g status-style bg=red
531 %elif #{==:#{host},myotherhost}
532 set -g status-style bg=green
533 %else
534 set -g status-style bg=blue
535 %endif
536 Will change the status line to red if running on ‘myhost’, green
538 if running on ‘myotherhost’, or blue if running on another host.
539 start-server
541 (alias: start)
542 Start the tmux server, if not already running, without creating
543 any sessions.
544 suspend-client [-t target-client]
546 (alias: suspendc)
547 Suspend a client by sending SIGTSTP (tty stop).
548 switch-client [-Elnpr] [-c target-client] [-t target-session] [-T
550 key-table]
551 (alias: switchc)
552 Switch the current session for client target-client to
553 target-session. If -l, -n or -p is used, the client is moved to
554 the last, next or previous session respectively. -r toggles
555 whether a client is read-only (see the attach-session command).
556 If -E is used, update-environment option will not be applied.
558 -T sets the client's key table; the next key from the client will
560 be interpreted from key-table. This may be used to configure
561 multiple prefix keys, or to bind commands to sequences of keys.
562 For example, to make typing ‘abc’ run the list-keys command:
563 bind-key -Ttable2 c list-keys
565 bind-key -Ttable1 b switch-client -Ttable2
566 bind-key -Troot a switch-client -Ttable1
567
569 A tmux window may be in one of two modes. The default permits direct
570 access to the terminal attached to the window. The other is copy mode,
571 which permits a section of a window or its history to be copied to a
572 paste buffer for later insertion into another window. This mode is
573 entered with the copy-mode command, bound to ‘[’ by default. It is also
574 entered when a command that produces output, such as list-keys, is exe‐
575 cuted from a key binding.
576 Commands are sent to copy mode using the -X flag to the send-keys com‐
578 mand. When a key is pressed, copy mode automatically uses one of two key
579 tables, depending on the mode-keys option: copy-mode for emacs, or
580 copy-mode-vi for vi. Key tables may be viewed with the list-keys com‐
581 mand.
582 The following commands are supported in copy mode:
584 Command vi emacs
586 append-selection
587 append-selection-and-cancel A
588 back-to-indentation ^ M-m
589 begin-selection Space C-Space
590 bottom-line L
591 cancel q Escape
592 clear-selection Escape C-g
593 copy-end-of-line D C-k
594 copy-line
595 copy-pipe <command>
596 copy-pipe-and-cancel <command>
597 copy-selection
598 copy-selection-and-cancel Enter M-w
599 cursor-down j Down
600 cursor-left h Left
601 cursor-right l Right
602 cursor-up k Up
603 end-of-line $ C-e
604 goto-line <line> : g
605 halfpage-down C-d M-Down
606 halfpage-down-and-cancel
607 halfpage-up C-u M-Up
608 history-bottom G M->
609 history-top g M-<
610 jump-again ; ;
611 jump-backward <to> F F
612 jump-forward <to> f f
613 jump-reverse , ,
614 jump-to-backward <to> T
615 jump-to-forward <to> t
616 middle-line M M-r
617 next-paragraph } M-}
618 next-space W
619 next-space-end E
620 next-word w
621 next-word-end e M-f
622 other-end o
623 page-down C-f PageDown
624 page-down-and-cancel
625 page-up C-b PageUp
626 previous-paragraph { M-{
627 previous-space B
628 previous-word b M-b
629 rectangle-toggle v R
630 scroll-down C-e C-Down
631 scroll-down-and-cancel
632 scroll-up C-y C-Up
633 search-again n n
634 search-backward <for> ?
635 search-forward <for> /
636 search-backward-incremental <for> C-r
637 search-forward-incremental <for> C-s
638 search-reverse N N
639 select-line V
640 start-of-line 0 C-a
641 stop-selection
642 top-line H M-R
643 The ‘-and-cancel’ variants of some commands exit copy mode after they
645 have completed (for copy commands) or when the cursor reaches the bottom
646 (for scrolling commands).
647 The next and previous word keys use space and the ‘-’, ‘_’ and ‘@’ char‐
649 acters as word delimiters by default, but this can be adjusted by setting
650 the word-separators session option. Next word moves to the start of the
651 next word, next word end to the end of the next word and previous word to
652 the start of the previous word. The three next and previous space keys
653 work similarly but use a space alone as the word separator.
654 The jump commands enable quick movement within a line. For instance,
656 typing ‘f’ followed by ‘/’ will move the cursor to the next ‘/’ character
657 on the current line. A ‘;’ will then jump to the next occurrence.
658 Commands in copy mode may be prefaced by an optional repeat count. With
660 vi key bindings, a prefix is entered using the number keys; with emacs,
661 the Alt (meta) key and a number begins prefix entry.
662 The synopsis for the copy-mode command is:
664 copy-mode [-Meu] [-t target-pane]
666 Enter copy mode. The -u option scrolls one page up. -M begins a
667 mouse drag (only valid if bound to a mouse key binding, see MOUSE
668 SUPPORT). -e specifies that scrolling to the bottom of the his‐
669 tory (to the visible screen) should exit copy mode. While in
670 copy mode, pressing a key other than those used for scrolling
671 will disable this behaviour. This is intended to allow fast
672 scrolling through a pane's history, for example with:
673 bind PageUp copy-mode -eu
675 Each window displayed by tmux may be split into one or more panes; each
677 pane takes up a certain area of the display and is a separate terminal.
678 A window may be split into panes using the split-window command. Windows
679 may be split horizontally (with the -h flag) or vertically. Panes may be
680 resized with the resize-pane command (bound to ‘C-Up’, ‘C-Down’ ‘C-Left’
681 and ‘C-Right’ by default), the current pane may be changed with the
682 select-pane command and the rotate-window and swap-pane commands may be
683 used to swap panes without changing their position. Panes are numbered
684 beginning from zero in the order they are created.
685 A number of preset layouts are available. These may be selected with the
687 select-layout command or cycled with next-layout (bound to ‘Space’ by
688 default); once a layout is chosen, panes within it may be moved and
689 resized as normal.
690 The following layouts are supported:
692 even-horizontal
694 Panes are spread out evenly from left to right across the window.
695 even-vertical
697 Panes are spread evenly from top to bottom.
698 main-horizontal
700 A large (main) pane is shown at the top of the window and the
701 remaining panes are spread from left to right in the leftover
702 space at the bottom. Use the main-pane-height window option to
703 specify the height of the top pane.
704 main-vertical
706 Similar to main-horizontal but the large pane is placed on the
707 left and the others spread from top to bottom along the right.
708 See the main-pane-width window option.
709 tiled Panes are spread out as evenly as possible over the window in
711 both rows and columns.
712 In addition, select-layout may be used to apply a previously used layout
714 - the list-windows command displays the layout of each window in a form
715 suitable for use with select-layout. For example:
716 $ tmux list-windows
718 0: ksh [159x48]
719 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
720 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
721 tmux automatically adjusts the size of the layout for the current window
723 size. Note that a layout cannot be applied to a window with more panes
724 than that from which the layout was originally defined.
725 Commands related to windows and panes are as follows:
727 break-pane [-dP] [-F format] [-n window-name] [-s src-pane] [-t
729 dst-window]
730 (alias: breakp)
731 Break src-pane off from its containing window to make it the only
732 pane in dst-window. If -d is given, the new window does not
733 become the current window. The -P option prints information
734 about the new window after it has been created. By default, it
735 uses the format ‘#{session_name}:#{window_index}’ but a different
736 format may be specified with -F.
737 capture-pane [-aepPqCJ] [-b buffer-name] [-E end-line] [-S start-line]
739 [-t target-pane]
740 (alias: capturep)
741 Capture the contents of a pane. If -p is given, the output goes
742 to stdout, otherwise to the buffer specified with -b or a new
743 buffer if omitted. If -a is given, the alternate screen is used,
744 and the history is not accessible. If no alternate screen
745 exists, an error will be returned unless -q is given. If -e is
746 given, the output includes escape sequences for text and back‐
747 ground attributes. -C also escapes non-printable characters as
748 octal \xxx. -J joins wrapped lines and preserves trailing spaces
749 at each line's end. -P captures only any output that the pane
750 has received that is the beginning of an as-yet incomplete escape
751 sequence.
752 -S and -E specify the starting and ending line numbers, zero is
754 the first line of the visible pane and negative numbers are lines
755 in the history. ‘-’ to -S is the start of the history and to -E
756 the end of the visible pane. The default is to capture only the
757 visible contents of the pane.
758 choose-client [-NZ] [-F format] [-f filter] [-O sort-order] [-t
760 target-pane] [template]
761 Put a pane into client mode, allowing a client to be selected
762 interactively from a list. -Z zooms the pane. The following
763 keys may be used in client mode:
764 Key Function
766 Enter Choose selected client
767 Up Select previous client
768 Down Select next client
769 C-s Search by name
770 n Repeat last search
771 t Toggle if client is tagged
772 T Tag no clients
773 C-t Tag all clients
774 d Detach selected client
775 D Detach tagged clients
776 x Detach and HUP selected client
777 X Detach and HUP tagged clients
778 z Suspend selected client
779 Z Suspend tagged clients
780 f Enter a format to filter items
781 O Change sort order
782 v Toggle preview
783 q Exit mode
784 After a client is chosen, ‘%%’ is replaced by the client name in
786 template and the result executed as a command. If template is
787 not given, "detach-client -t '%%'" is used.
788 -O specifies the initial sort order: one of ‘name’, ‘size’,
790 ‘creation’, or ‘activity’. -f specifies an initial filter: the
791 filter is a format - if it evaluates to zero, the item in the
792 list is not shown, otherwise it is shown. If a filter would lead
793 to an empty list, it is ignored. -F specifies the format for
794 each item in the list. -N starts without the preview. This com‐
795 mand works only if at least one client is attached.
796 choose-tree [-GNswZ] [-F format] [-f filter] [-O sort-order] [-t
798 target-pane] [template]
799 Put a pane into tree mode, where a session, window or pane may be
800 chosen interactively from a list. -s starts with sessions col‐
801 lapsed and -w with windows collapsed. -Z zooms the pane. The
802 following keys may be used in tree mode:
803 Key Function
805 Enter Choose selected item
806 Up Select previous item
807 Down Select next item
808 x Kill selected item
809 X Kill tagged items
810 < Scroll list of previews left
811 > Scroll list of previews right
812 C-s Search by name
813 n Repeat last search
814 t Toggle if item is tagged
815 T Tag no items
816 C-t Tag all items
817 : Run a command for each tagged item
818 f Enter a format to filter items
819 O Change sort order
820 v Toggle preview
821 q Exit mode
822 After a session, window or pane is chosen, ‘%%’ is replaced by
824 the target in template and the result executed as a command. If
825 template is not given, "switch-client -t '%%'" is used.
826 -O specifies the initial sort order: one of ‘index’, ‘name’, or
828 ‘time’. -f specifies an initial filter: the filter is a format -
829 if it evaluates to zero, the item in the list is not shown, oth‐
830 erwise it is shown. If a filter would lead to an empty list, it
831 is ignored. -F specifies the format for each item in the tree.
832 -N starts without the preview. -G includes all sessions in any
833 session groups in the tree rather than only the first. This com‐
834 mand works only if at least one client is attached.
835 display-panes [-b] [-d duration] [-t target-client] [template]
837 (alias: displayp)
838 Display a visible indicator of each pane shown by target-client.
839 See the display-panes-colour and display-panes-active-colour ses‐
840 sion options. The indicator is closed when a key is pressed or
841 duration milliseconds have passed. If -d is not given,
842 display-panes-time is used. A duration of zero means the indica‐
843 tor stays until a key is pressed. While the indicator is on
844 screen, a pane may be chosen with the ‘0’ to ‘9’ keys, which will
845 cause template to be executed as a command with ‘%%’ substituted
846 by the pane ID. The default template is "select-pane -t '%%'".
847 With -b, other commands are not blocked from running until the
848 indicator is closed.
849 find-window [-CNTZ] [-t target-pane] match-string
851 (alias: findw)
852 Search for the fnmatch(3) pattern match-string in window names,
853 titles, and visible content (but not history). The flags control
854 matching behavior: -C matches only visible window contents, -N
855 matches only the window name and -T matches only the window
856 title. The default is -CNT. -Z zooms the pane.
857 This command works only if at least one client is attached.
859 join-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane]
861 (alias: joinp)
862 Like split-window, but instead of splitting dst-pane and creating
863 a new pane, split it and move src-pane into the space. This can
864 be used to reverse break-pane. The -b option causes src-pane to
865 be joined to left of or above dst-pane.
866 If -s is omitted and a marked pane is present (see select-pane
868 -m), the marked pane is used rather than the current pane.
869 kill-pane [-a] [-t target-pane]
871 (alias: killp)
872 Destroy the given pane. If no panes remain in the containing
873 window, it is also destroyed. The -a option kills all but the
874 pane given with -t.
875 kill-window [-a] [-t target-window]
877 (alias: killw)
878 Kill the current window or the window at target-window, removing
879 it from any sessions to which it is linked. The -a option kills
880 all but the window given with -t.
881 last-pane [-de] [-t target-window]
883 (alias: lastp)
884 Select the last (previously selected) pane. -e enables or -d
885 disables input to the pane.
886 last-window [-t target-session]
888 (alias: last)
889 Select the last (previously selected) window. If no
890 target-session is specified, select the last window of the cur‐
891 rent session.
892 link-window [-adk] [-s src-window] [-t dst-window]
894 (alias: linkw)
895 Link the window at src-window to the specified dst-window. If
896 dst-window is specified and no such window exists, the src-window
897 is linked there. With -a, the window is moved to the next index
898 up (following windows are moved if necessary). If -k is given
899 and dst-window exists, it is killed, otherwise an error is gener‐
900 ated. If -d is given, the newly linked window is not selected.
901 list-panes [-as] [-F format] [-t target]
903 (alias: lsp)
904 If -a is given, target is ignored and all panes on the server are
905 listed. If -s is given, target is a session (or the current ses‐
906 sion). If neither is given, target is a window (or the current
907 window). For the meaning of the -F flag, see the FORMATS sec‐
908 tion.
909 list-windows [-a] [-F format] [-t target-session]
911 (alias: lsw)
912 If -a is given, list all windows on the server. Otherwise, list
913 windows in the current session or in target-session. For the
914 meaning of the -F flag, see the FORMATS section.
915 move-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane]
917 (alias: movep)
918 Like join-pane, but src-pane and dst-pane may belong to the same
919 window.
920 move-window [-ardk] [-s src-window] [-t dst-window]
922 (alias: movew)
923 This is similar to link-window, except the window at src-window
924 is moved to dst-window. With -r, all windows in the session are
925 renumbered in sequential order, respecting the base-index option.
926 new-window [-adkP] [-c start-directory] [-F format] [-n window-name] [-t
928 target-window] [shell-command]
929 (alias: neww)
930 Create a new window. With -a, the new window is inserted at the
931 next index up from the specified target-window, moving windows up
932 if necessary, otherwise target-window is the new window location.
933 If -d is given, the session does not make the new window the cur‐
935 rent window. target-window represents the window to be created;
936 if the target already exists an error is shown, unless the -k
937 flag is used, in which case it is destroyed. shell-command is
938 the command to execute. If shell-command is not specified, the
939 value of the default-command option is used. -c specifies the
940 working directory in which the new window is created.
941 When the shell command completes, the window closes. See the
943 remain-on-exit option to change this behaviour.
944 The TERM environment variable must be set to ‘screen’ or ‘tmux’
946 for all programs running inside tmux. New windows will automati‐
947 cally have ‘TERM=screen’ added to their environment, but care
948 must be taken not to reset this in shell start-up files.
949 The -P option prints information about the new window after it
951 has been created. By default, it uses the format
952 ‘#{session_name}:#{window_index}’ but a different format may be
953 specified with -F.
954 next-layout [-t target-window]
956 (alias: nextl)
957 Move a window to the next layout and rearrange the panes to fit.
958 next-window [-a] [-t target-session]
960 (alias: next)
961 Move to the next window in the session. If -a is used, move to
962 the next window with an alert.
963 pipe-pane [-IOo] [-t target-pane] [shell-command]
965 (alias: pipep)
966 Pipe output sent by the program in target-pane to a shell command
967 or vice versa. A pane may only be connected to one command at a
968 time, any existing pipe is closed before shell-command is exe‐
969 cuted. The shell-command string may contain the special charac‐
970 ter sequences supported by the status-left option. If no
971 shell-command is given, the current pipe (if any) is closed.
972 -I and -O specify which of the shell-command output streams are
974 connected to the pane: with -I stdout is connected (so anything
975 shell-command prints is written to the pane as if it were typed);
976 with -O stdin is connected (so any output in the pane is piped to
977 shell-command). Both may be used together and if neither are
978 specified, -O is used.
979 The -o option only opens a new pipe if no previous pipe exists,
981 allowing a pipe to be toggled with a single key, for example:
982 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
984 previous-layout [-t target-window]
986 (alias: prevl)
987 Move to the previous layout in the session.
988 previous-window [-a] [-t target-session]
990 (alias: prev)
991 Move to the previous window in the session. With -a, move to the
992 previous window with an alert.
993 rename-window [-t target-window] new-name
995 (alias: renamew)
996 Rename the current window, or the window at target-window if
997 specified, to new-name.
998 resize-pane [-DLMRUZ] [-t target-pane] [-x width] [-y height]
1000 [adjustment]
1001 (alias: resizep)
1002 Resize a pane, up, down, left or right by adjustment with -U, -D,
1003 -L or -R, or to an absolute size with -x or -y. The adjustment
1004 is given in lines or cells (the default is 1).
1005 With -Z, the active pane is toggled between zoomed (occupying the
1007 whole of the window) and unzoomed (its normal position in the
1008 layout).
1009 -M begins mouse resizing (only valid if bound to a mouse key
1011 binding, see MOUSE SUPPORT).
1012 resize-window [-aADLRU] [-t target-window] [-x width] [-y height]
1014 [adjustment]
1015 (alias: resizew)
1016 Resize a window, up, down, left or right by adjustment with -U,
1017 -D, -L or -R, or to an absolute size with -x or -y. The
1018 adjustment is given in lines or cells (the default is 1). -A
1019 sets the size of the largest session containing the window; -a
1020 the size of the smallest. This command will automatically set
1021 window-size to manual in the window options.
1022 respawn-pane [-c start-directory] [-k] [-t target-pane] [shell-command]
1024 (alias: respawnp)
1025 Reactivate a pane in which the command has exited (see the
1026 remain-on-exit window option). If shell-command is not given,
1027 the command used when the pane was created is executed. The pane
1028 must be already inactive, unless -k is given, in which case any
1029 existing command is killed. -c specifies a new working directory
1030 for the pane.
1031 respawn-window [-c start-directory] [-k] [-t target-window]
1033 [shell-command]
1034 (alias: respawnw)
1035 Reactivate a window in which the command has exited (see the
1036 remain-on-exit window option). If shell-command is not given,
1037 the command used when the window was created is executed. The
1038 window must be already inactive, unless -k is given, in which
1039 case any existing command is killed. -c specifies a new working
1040 directory for the window.
1041 rotate-window [-DU] [-t target-window]
1043 (alias: rotatew)
1044 Rotate the positions of the panes within a window, either upward
1045 (numerically lower) with -U or downward (numerically higher).
1046 select-layout [-Enop] [-t target-pane] [layout-name]
1048 (alias: selectl)
1049 Choose a specific layout for a window. If layout-name is not
1050 given, the last preset layout used (if any) is reapplied. -n and
1051 -p are equivalent to the next-layout and previous-layout com‐
1052 mands. -o applies the last set layout if possible (undoes the
1053 most recent layout change). -E spreads the current pane and any
1054 panes next to it out evenly.
1055 select-pane [-DdegLlMmRU] [-P style] [-T title] [-t target-pane]
1057 (alias: selectp)
1058 Make pane target-pane the active pane in window target-window, or
1059 set its style (with -P). If one of -D, -L, -R, or -U is used,
1060 respectively the pane below, to the left, to the right, or above
1061 the target pane is used. -l is the same as using the last-pane
1062 command. -e enables or -d disables input to the pane.
1063 -m and -M are used to set and clear the marked pane. There is
1065 one marked pane at a time, setting a new marked pane clears the
1066 last. The marked pane is the default target for -s to join-pane,
1067 swap-pane and swap-window.
1068 Each pane has a style: by default the window-style and
1070 window-active-style options are used, select-pane -P sets the
1071 style for a single pane. For example, to set the pane 1 back‐
1072 ground to red:
1073 select-pane -t:.1 -P 'bg=red'
1075 -g shows the current pane style.
1077 -T sets the pane title.
1079 select-window [-lnpT] [-t target-window]
1081 (alias: selectw)
1082 Select the window at target-window. -l, -n and -p are equivalent
1083 to the last-window, next-window and previous-window commands. If
1084 -T is given and the selected window is already the current win‐
1085 dow, the command behaves like last-window.
1086 split-window [-bdfhvP] [-c start-directory] [-l size | -p percentage] [-t
1088 target-pane] [shell-command] [-F format]
1089 (alias: splitw)
1090 Create a new pane by splitting target-pane: -h does a horizontal
1091 split and -v a vertical split; if neither is specified, -v is
1092 assumed. The -l and -p options specify the size of the new pane
1093 in lines (for vertical split) or in cells (for horizontal split),
1094 or as a percentage, respectively. The -b option causes the new
1095 pane to be created to the left of or above target-pane. The -f
1096 option creates a new pane spanning the full window height (with
1097 -h) or full window width (with -v), instead of splitting the
1098 active pane. All other options have the same meaning as for the
1099 new-window command.
1100 swap-pane [-dDU] [-s src-pane] [-t dst-pane]
1102 (alias: swapp)
1103 Swap two panes. If -U is used and no source pane is specified
1104 with -s, dst-pane is swapped with the previous pane (before it
1105 numerically); -D swaps with the next pane (after it numerically).
1106 -d instructs tmux not to change the active pane.
1107 If -s is omitted and a marked pane is present (see select-pane
1109 -m), the marked pane is used rather than the current pane.
1110 swap-window [-d] [-s src-window] [-t dst-window]
1112 (alias: swapw)
1113 This is similar to link-window, except the source and destination
1114 windows are swapped. It is an error if no window exists at
1115 src-window.
1116 Like swap-pane, if -s is omitted and a marked pane is present
1118 (see select-pane -m), the window containing the marked pane is
1119 used rather than the current window.
1120 unlink-window [-k] [-t target-window]
1122 (alias: unlinkw)
1123 Unlink target-window. Unless -k is given, a window may be
1124 unlinked only if it is linked to multiple sessions - windows may
1125 not be linked to no sessions; if -k is specified and the window
1126 is linked to only one session, it is unlinked and destroyed.
1127
1129 tmux allows a command to be bound to most keys, with or without a prefix
1130 key. When specifying keys, most represent themselves (for example ‘A’ to
1131 ‘Z’). Ctrl keys may be prefixed with ‘C-’ or ‘^’, and Alt (meta) with
1132 ‘M-’. In addition, the following special key names are accepted: Up,
1133 Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to
1134 F12, Home, IC (Insert), NPage/PageDown/PgDn, PPage/PageUp/PgUp, Space,
1135 and Tab. Note that to bind the ‘"’ or ‘'’ keys, quotation marks are nec‐
1136 essary, for example:
1137 bind-key '"' split-window
1139 bind-key "'" new-window
1140 Commands related to key bindings are as follows:
1142 bind-key [-nr] [-T key-table] key command [arguments]
1144 (alias: bind)
1145 Bind key key to command. Keys are bound in a key table. By
1146 default (without -T), the key is bound in the prefix key table.
1147 This table is used for keys pressed after the prefix key (for
1148 example, by default ‘c’ is bound to new-window in the prefix ta‐
1149 ble, so ‘C-b c’ creates a new window). The root table is used
1150 for keys pressed without the prefix key: binding ‘c’ to
1151 new-window in the root table (not recommended) means a plain ‘c’
1152 will create a new window. -n is an alias for -T root. Keys may
1153 also be bound in custom key tables and the switch-client -T com‐
1154 mand used to switch to them from a key binding. The -r flag
1155 indicates this key may repeat, see the repeat-time option.
1156 To view the default bindings and possible commands, see the
1158 list-keys command.
1159 list-keys [-T key-table]
1161 (alias: lsk)
1162 List all key bindings. Without -T all key tables are printed.
1163 With -T only key-table.
1164 send-keys [-lMRX] [-N repeat-count] [-t target-pane] key ...
1166 (alias: send)
1167 Send a key or keys to a window. Each argument key is the name of
1168 the key (such as ‘C-a’ or ‘NPage’) to send; if the string is not
1169 recognised as a key, it is sent as a series of characters. The
1170 -l flag disables key name lookup and sends the keys literally.
1171 All arguments are sent sequentially from first to last. The -R
1172 flag causes the terminal state to be reset.
1173 -M passes through a mouse event (only valid if bound to a mouse
1175 key binding, see MOUSE SUPPORT).
1176 -X is used to send a command into copy mode - see the WINDOWS AND
1178 PANES section. -N specifies a repeat count.
1179 send-prefix [-2] [-t target-pane]
1181 Send the prefix key, or with -2 the secondary prefix key, to a
1182 window as if it was pressed.
1183 unbind-key [-an] [-T key-table] key
1185 (alias: unbind)
1186 Unbind the command bound to key. -n and -T are the same as for
1187 bind-key. If -a is present, all key bindings are removed.
1188
1190 The appearance and behaviour of tmux may be modified by changing the
1191 value of various options. There are three types of option: server
1192 options, session options and window options.
1193 The tmux server has a set of global options which do not apply to any
1195 particular window or session. These are altered with the set-option -s
1196 command, or displayed with the show-options -s command.
1197 In addition, each individual session may have a set of session options,
1199 and there is a separate set of global session options. Sessions which do
1200 not have a particular option configured inherit the value from the global
1201 session options. Session options are set or unset with the set-option
1202 command and may be listed with the show-options command. The available
1203 server and session options are listed under the set-option command.
1204 Similarly, a set of window options is attached to each window, and there
1206 is a set of global window options from which any unset options are inher‐
1207 ited. Window options are altered with the set-window-option command and
1208 can be listed with the show-window-options command. All window options
1209 are documented with the set-window-option command.
1210 tmux also supports user options which are prefixed with a ‘@’. User
1212 options may have any name, so long as they are prefixed with ‘@’, and be
1213 set to any string. For example:
1214 $ tmux setw -q @foo "abc123"
1216 $ tmux showw -v @foo
1217 abc123
1218 Commands which set options are as follows:
1220 set-option [-aFgoqsuw] [-t target-session | target-window] option value
1222 (alias: set)
1223 Set a window option with -w (equivalent to the set-window-option
1224 command), a server option with -s, otherwise a session option.
1225 If -g is given, the global session or window option is set. -F
1226 expands formats in the option value. The -u flag unsets an
1227 option, so a session inherits the option from the global options
1228 (or with -g, restores a global option to the default).
1229 The -o flag prevents setting an option that is already set and
1231 the -q flag suppresses errors about unknown or ambiguous options.
1232 With -a, and if the option expects a string or a style, value is
1234 appended to the existing setting. For example:
1235 set -g status-left "foo"
1237 set -ag status-left "bar"
1238 Will result in ‘foobar’. And:
1240 set -g status-style "bg=red"
1242 set -ag status-style "fg=blue"
1243 Will result in a red background and blue foreground. Without -a,
1245 the result would be the default background and a blue foreground.
1246 Available window options are listed under set-window-option.
1248 value depends on the option and may be a number, a string, or a
1250 flag (on, off, or omitted to toggle).
1251 Available server options are:
1253 buffer-limit number
1255 Set the number of buffers; as new buffers are added to
1256 the top of the stack, old ones are removed from the bot‐
1257 tom if necessary to maintain this maximum length.
1258 command-alias[] name=value
1260 This is an array of custom aliases for commands. If an
1261 unknown command matches name, it is replaced with value.
1262 For example, after:
1263 set -s command-alias[100] zoom='resize-pane -Z'
1265 Using:
1267 zoom -t:.1
1269 Is equivalent to:
1271 resize-pane -Z -t:.1
1273 Note that aliases are expanded when a command is parsed
1275 rather than when it is executed, so binding an alias with
1276 bind-key will bind the expanded form.
1277 default-terminal terminal
1279 Set the default terminal for new windows created in this
1280 session - the default value of the TERM environment vari‐
1281 able. For tmux to work correctly, this must be set to
1282 ‘screen’, ‘tmux’ or a derivative of them.
1283 escape-time time
1285 Set the time in milliseconds for which tmux waits after
1286 an escape is input to determine if it is part of a func‐
1287 tion or meta key sequences. The default is 500 millisec‐
1288 onds.
1289 exit-empty [on | off]
1291 If enabled (the default), the server will exit when there
1292 are no active sessions.
1293 exit-unattached [on | off]
1295 If enabled, the server will exit when there are no
1296 attached clients.
1297 focus-events [on | off]
1299 When enabled, focus events are requested from the termi‐
1300 nal if supported and passed through to applications run‐
1301 ning in tmux. Attached clients should be detached and
1302 attached again after changing this option.
1303 history-file path
1305 If not empty, a file to which tmux will write command
1306 prompt history on exit and load it from on start.
1307 message-limit number
1309 Set the number of error or information messages to save
1310 in the message log for each client. The default is 100.
1311 set-clipboard [on | external | off]
1313 Attempt to set the terminal clipboard content using the
1314 xterm(1) escape sequence, if there is an Ms entry in the
1315 terminfo(5) description (see the TERMINFO EXTENSIONS sec‐
1316 tion).
1317 If set to on, tmux will both accept the escape sequence
1319 to create a buffer and attempt to set the terminal clip‐
1320 board. If set to external, tmux will attempt to set the
1321 terminal clipboard but ignore attempts by applications to
1322 set tmux buffers. If off, tmux will neither accept the
1323 clipboard escape sequence nor attempt to set the clip‐
1324 board.
1325 Note that this feature needs to be enabled in xterm(1) by
1327 setting the resource:
1328 disallowedWindowOps: 20,21,SetXprop
1330 Or changing this property from the xterm(1) interactive
1332 menu when required.
1333 terminal-overrides[] string
1335 Allow terminal descriptions read using terminfo(5) to be
1336 overridden. Each entry is a colon-separated string made
1337 up of a terminal type pattern (matched using fnmatch(3))
1338 and a set of name=value entries.
1339 For example, to set the ‘clear’ terminfo(5) entry to
1341 ‘\e[H\e[2J’ for all terminal types matching ‘rxvt*’:
1342 rxvt*:clear=\e[H\e[2J
1344 The terminal entry value is passed through strunvis(3)
1346 before interpretation.
1347 Available session options are:
1349 activity-action [any | none | current | other]
1351 Set action on window activity when monitor-activity is
1352 on. any means activity in any window linked to a session
1353 causes a bell or message (depending on visual-activity)
1354 in the current window of that session, none means all
1355 activity is ignored (equivalent to monitor-activity being
1356 off), current means only activity in windows other than
1357 the current window are ignored and other means activity
1358 in the current window is ignored but not those in other
1359 windows.
1360 assume-paste-time milliseconds
1362 If keys are entered faster than one in milliseconds, they
1363 are assumed to have been pasted rather than typed and
1364 tmux key bindings are not processed. The default is one
1365 millisecond and zero disables.
1366 base-index index
1368 Set the base index from which an unused index should be
1369 searched when a new window is created. The default is
1370 zero.
1371 bell-action [any | none | current | other]
1373 Set action on a bell in a window when monitor-bell is on.
1374 The values are the same as those for activity-action.
1375 default-command shell-command
1377 Set the command used for new windows (if not specified
1378 when the window is created) to shell-command, which may
1379 be any sh(1) command. The default is an empty string,
1380 which instructs tmux to create a login shell using the
1381 value of the default-shell option.
1382 default-size XxY
1384 Set the default size of new windows when the window-size
1385 option is set to manual or when a session is created with
1386 new-session -d. The value is the width and height sepa‐
1387 rated by an ‘x’ character. The default is 80x24.
1388 default-shell path
1390 Specify the default shell. This is used as the login
1391 shell for new windows when the default-command option is
1392 set to empty, and must be the full path of the exe‐
1393 cutable. When started tmux tries to set a default value
1394 from the first suitable of the SHELL environment vari‐
1395 able, the shell returned by getpwuid(3), or /bin/sh.
1396 This option should be configured when tmux is used as a
1397 login shell.
1398 default-size XxY
1400 Set the default size of windows when the size is not set
1401 or the window-size option is manual.
1402 destroy-unattached [on | off]
1404 If enabled and the session is no longer attached to any
1405 clients, it is destroyed.
1406 detach-on-destroy [on | off]
1408 If on (the default), the client is detached when the ses‐
1409 sion it is attached to is destroyed. If off, the client
1410 is switched to the most recently active of the remaining
1411 sessions.
1412 display-panes-active-colour colour
1414 Set the colour used by the display-panes command to show
1415 the indicator for the active pane.
1416 display-panes-colour colour
1418 Set the colour used by the display-panes command to show
1419 the indicators for inactive panes.
1420 display-panes-time time
1422 Set the time in milliseconds for which the indicators
1423 shown by the display-panes command appear.
1424 display-time time
1426 Set the amount of time for which status line messages and
1427 other on-screen indicators are displayed. If set to 0,
1428 messages and indicators are displayed until a key is
1429 pressed. time is in milliseconds.
1430 history-limit lines
1432 Set the maximum number of lines held in window history.
1433 This setting applies only to new windows - existing win‐
1434 dow histories are not resized and retain the limit at the
1435 point they were created.
1436 key-table key-table
1438 Set the default key table to key-table instead of root.
1439 lock-after-time number
1441 Lock the session (like the lock-session command) after
1442 number seconds of inactivity. The default is not to lock
1443 (set to 0).
1444 lock-command shell-command
1446 Command to run when locking each client. The default is
1447 to run lock(1) with -np.
1448 message-command-style style
1450 Set status line message command style. For how to spec‐
1451 ify style, see the STYLES section.
1452 message-style style
1454 Set status line message style. For how to specify style,
1455 see the STYLES section.
1456 mouse [on | off]
1458 If on, tmux captures the mouse and allows mouse events to
1459 be bound as key bindings. See the MOUSE SUPPORT section
1460 for details.
1461 prefix key
1463 Set the key accepted as a prefix key. In addition to the
1464 standard keys described under KEY BINDINGS, prefix can be
1465 set to the special key ‘None’ to set no prefix.
1466 prefix2 key
1468 Set a secondary key accepted as a prefix key. Like
1469 prefix, prefix2 can be set to ‘None’.
1470 renumber-windows [on | off]
1472 If on, when a window is closed in a session, automati‐
1473 cally renumber the other windows in numerical order.
1474 This respects the base-index option if it has been set.
1475 If off, do not renumber the windows.
1476 repeat-time time
1478 Allow multiple commands to be entered without pressing
1479 the prefix-key again in the specified time milliseconds
1480 (the default is 500). Whether a key repeats may be set
1481 when it is bound using the -r flag to bind-key. Repeat
1482 is enabled for the default keys bound to the resize-pane
1483 command.
1484 set-titles [on | off]
1486 Attempt to set the client terminal title using the tsl
1487 and fsl terminfo(5) entries if they exist. tmux automat‐
1488 ically sets these to the \e]0;...\007 sequence if the
1489 terminal appears to be xterm(1). This option is off by
1490 default.
1491 set-titles-string string
1493 String used to set the window title if set-titles is on.
1494 Formats are expanded, see the FORMATS section.
1495 silence-action [any | none | current | other]
1497 Set action on window silence when monitor-silence is on.
1498 The values are the same as those for activity-action.
1499 status [off | on | 2 | 3 | 4 | 5]
1501 Show or hide the status line or specify its size. Using
1502 on gives a status line one row in height; 2, 3, 4 or 5
1503 more rows.
1504 status-format[] format
1506 Specify the format to be used for each line of the status
1507 line. The default builds the top status line from the
1508 various individual status options below.
1509 status-interval interval
1511 Update the status line every interval seconds. By
1512 default, updates will occur every 15 seconds. A setting
1513 of zero disables redrawing at interval.
1514 status-justify [left | centre | right]
1516 Set the position of the window list component of the sta‐
1517 tus line: left, centre or right justified.
1518 status-keys [vi | emacs]
1520 Use vi or emacs-style key bindings in the status line,
1521 for example at the command prompt. The default is emacs,
1522 unless the VISUAL or EDITOR environment variables are set
1523 and contain the string ‘vi’.
1524 status-left string
1526 Display string (by default the session name) to the left
1527 of the status line. string will be passed through
1528 strftime(3). Also see the FORMATS and STYLES sections.
1529 For details on how the names and titles can be set see
1531 the NAMES AND TITLES section.
1532 Examples are:
1534 #(sysctl vm.loadavg)
1536 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
1537 The default is ‘[#S] ’.
1539 status-left-length length
1541 Set the maximum length of the left component of the sta‐
1542 tus line. The default is 10.
1543 status-left-style style
1545 Set the style of the left part of the status line. For
1546 how to specify style, see the STYLES section.
1547 status-position [top | bottom]
1549 Set the position of the status line.
1550 status-right string
1552 Display string to the right of the status line. By
1553 default, the current pane title in double quotes, the
1554 date and the time are shown. As with status-left, string
1555 will be passed to strftime(3) and character pairs are
1556 replaced.
1557 status-right-length length
1559 Set the maximum length of the right component of the sta‐
1560 tus line. The default is 40.
1561 status-right-style style
1563 Set the style of the right part of the status line. For
1564 how to specify style, see the STYLES section.
1565 status-style style
1567 Set status line style. For how to specify style, see the
1568 STYLES section.
1569 update-environment[] variable
1571 Set list of environment variables to be copied into the
1572 session environment when a new session is created or an
1573 existing session is attached. Any variables that do not
1574 exist in the source environment are set to be removed
1575 from the session environment (as if -r was given to the
1576 set-environment command).
1577 user-keys[] key
1579 Set list of user-defined key escape sequences. Each item
1580 is associated with a key named ‘User0’, ‘User1’, and so
1581 on.
1582 For example:
1584 set -s user-keys[0] "\e[5;30012~"
1586 bind User0 resize-pane -L 3
1587 visual-activity [on | off | both]
1589 If on, display a message instead of sending a bell when
1590 activity occurs in a window for which the
1591 monitor-activity window option is enabled. If set to
1592 both, a bell and a message are produced.
1593 visual-bell [on | off | both]
1595 If on, a message is shown on a bell in a window for which
1596 the monitor-bell window option is enabled instead of it
1597 being passed through to the terminal (which normally
1598 makes a sound). If set to both, a bell and a message are
1599 produced. Also see the bell-action option.
1600 visual-silence [on | off | both]
1602 If monitor-silence is enabled, prints a message after the
1603 interval has expired on a given window instead of sending
1604 a bell. If set to both, a bell and a message are pro‐
1605 duced.
1606 word-separators string
1608 Sets the session's conception of what characters are con‐
1609 sidered word separators, for the purposes of the next and
1610 previous word commands in copy mode. The default is
1611 ‘ -_@’.
1612 set-window-option [-aFgoqu] [-t target-window] option value
1614 (alias: setw)
1615 Set a window option. The -a, -F, -g, -o, -q and -u flags work
1616 similarly to the set-option command.
1617 Supported window options are:
1619 aggressive-resize [on | off]
1621 Aggressively resize the chosen window. This means that
1622 tmux will resize the window to the size of the smallest
1623 or largest session (see the window-size option) for which
1624 it is the current window, rather than the session to
1625 which it is attached. The window may resize when the
1626 current window is changed on another session; this option
1627 is good for full-screen programs which support SIGWINCH
1628 and poor for interactive programs such as shells.
1629 allow-rename [on | off]
1631 Allow programs to change the window name using a terminal
1632 escape sequence (\ek...\e\\). The default is off.
1633 alternate-screen [on | off]
1635 This option configures whether programs running inside
1636 tmux may use the terminal alternate screen feature, which
1637 allows the smcup and rmcup terminfo(5) capabilities. The
1638 alternate screen feature preserves the contents of the
1639 window when an interactive application starts and
1640 restores it on exit, so that any output visible before
1641 the application starts reappears unchanged after it
1642 exits. The default is on.
1643 automatic-rename [on | off]
1645 Control automatic window renaming. When this setting is
1646 enabled, tmux will rename the window automatically using
1647 the format specified by automatic-rename-format. This
1648 flag is automatically disabled for an individual window
1649 when a name is specified at creation with new-window or
1650 new-session, or later with rename-window, or with a ter‐
1651 minal escape sequence. It may be switched off globally
1652 with:
1653 set-window-option -g automatic-rename off
1655 automatic-rename-format format
1657 The format (see FORMATS) used when the automatic-rename
1658 option is enabled.
1659 clock-mode-colour colour
1661 Set clock colour.
1662 clock-mode-style [12 | 24]
1664 Set clock hour format.
1665 main-pane-height height
1667 main-pane-width width
1668 Set the width or height of the main (left or top) pane in
1669 the main-horizontal or main-vertical layouts.
1670 mode-keys [vi | emacs]
1672 Use vi or emacs-style key bindings in copy mode. The
1673 default is emacs, unless VISUAL or EDITOR contains ‘vi’.
1674 mode-style style
1676 Set window modes style. For how to specify style, see
1677 the STYLES section.
1678 monitor-activity [on | off]
1680 Monitor for activity in the window. Windows with activ‐
1681 ity are highlighted in the status line.
1682 monitor-bell [on | off]
1684 Monitor for a bell in the window. Windows with a bell
1685 are highlighted in the status line.
1686 monitor-silence [interval]
1688 Monitor for silence (no activity) in the window within
1689 interval seconds. Windows that have been silent for the
1690 interval are highlighted in the status line. An interval
1691 of zero disables the monitoring.
1692 other-pane-height height
1694 Set the height of the other panes (not the main pane) in
1695 the main-horizontal layout. If this option is set to 0
1696 (the default), it will have no effect. If both the
1697 main-pane-height and other-pane-height options are set,
1698 the main pane will grow taller to make the other panes
1699 the specified height, but will never shrink to do so.
1700 other-pane-width width
1702 Like other-pane-height, but set the width of other panes
1703 in the main-vertical layout.
1704 pane-active-border-style style
1706 Set the pane border style for the currently active pane.
1707 For how to specify style, see the STYLES section.
1708 Attributes are ignored.
1709 pane-base-index index
1711 Like base-index, but set the starting index for pane num‐
1712 bers.
1713 pane-border-format format
1715 Set the text shown in pane border status lines.
1716 pane-border-status [off | top | bottom]
1718 Turn pane border status lines off or set their position.
1719 pane-border-style style
1721 Set the pane border style for panes aside from the active
1722 pane. For how to specify style, see the STYLES section.
1723 Attributes are ignored.
1724 remain-on-exit [on | off]
1726 A window with this flag set is not destroyed when the
1727 program running in it exits. The window may be reacti‐
1728 vated with the respawn-window command.
1729 synchronize-panes [on | off]
1731 Duplicate input to any pane to all other panes in the
1732 same window (only for panes that are not in any special
1733 mode).
1734 window-active-style style
1736 Set the style for the window's active pane. For how to
1737 specify style, see the STYLES section.
1738 window-status-activity-style style
1740 Set status line style for windows with an activity alert.
1741 For how to specify style, see the STYLES section.
1742 window-status-bell-style style
1744 Set status line style for windows with a bell alert. For
1745 how to specify style, see the STYLES section.
1746 window-status-current-format string
1748 Like window-status-format, but is the format used when
1749 the window is the current window.
1750 window-status-current-style style
1752 Set status line style for the currently active window.
1753 For how to specify style, see the STYLES section.
1754 window-status-format string
1756 Set the format in which the window is displayed in the
1757 status line window list. See the FORMATS and STYLES sec‐
1758 tions.
1759 window-status-last-style style
1761 Set status line style for the last active window. For
1762 how to specify style, see the STYLES section.
1763 window-status-separator string
1765 Sets the separator drawn between windows in the status
1766 line. The default is a single space character.
1767 window-status-style style
1769 Set status line style for a single window. For how to
1770 specify style, see the STYLES section.
1771 window-size largest | smallest | manual
1773 Configure how tmux determines the window size. If set to
1774 largest, the size of the largest attached session is
1775 used; if smallest, the size of the smallest. If manual,
1776 the size of a new window is set from the default-size
1777 option and windows are resized automatically. See also
1778 the resize-window command and the aggressive-resize
1779 option.
1780 window-style style
1782 Set the default window style. For how to specify style,
1783 see the STYLES section.
1784 window-size [smallest | largest | manual]
1786 Tell tmux how to automatically size windows either the
1787 size of the smallest session containing the window, the
1788 size of the largest, or manual size. See also the
1789 resize-window command and the default-size and
1790 aggressive-resize options.
1791 wrap-search [on | off]
1793 If this option is set, searches will wrap around the end
1794 of the pane contents. The default is on.
1795 xterm-keys [on | off]
1797 If this option is set, tmux will generate xterm(1) -style
1798 function key sequences; these have a number included to
1799 indicate modifiers such as Shift, Alt or Ctrl.
1800 show-options [-gqsvw] [-t target-session | target-window] [option]
1802 (alias: show)
1803 Show the window options (or a single window option if given) with
1804 -w (equivalent to show-window-options), the server options with
1805 -s, otherwise the session options for target session. Global
1806 session or window options are listed if -g is used. -v shows
1807 only the option value, not the name. If -q is set, no error will
1808 be returned if option is unset.
1809 show-window-options [-gv] [-t target-window] [option]
1811 (alias: showw)
1812 List the window options or a single option for target-window, or
1813 the global window options if -g is used. -v shows only the
1814 option value, not the name.
1815
1817 tmux allows commands to run on various triggers, called hooks. Most tmux
1818 commands have an after hook and there are a number of hooks not associ‐
1819 ated with commands.
1820 A command's after hook is run after it completes, except when the command
1822 is run as part of a hook itself. They are named with an ‘after-’ prefix.
1823 For example, the following command adds a hook to select the even-verti‐
1824 cal layout after every split-window:
1825 set-hook after-split-window "selectl even-vertical"
1827 All the notifications listed in the CONTROL MODE section are hooks (with‐
1829 out any arguments), except %exit. The following additional hooks are
1830 available:
1831 alert-activity Run when a window has activity. See
1833 monitor-activity.
1834 alert-bell Run when a window has received a bell. See
1836 monitor-bell.
1837 alert-silence Run when a window has been silent. See
1839 monitor-silence.
1840 client-attached Run when a client is attached.
1842 client-detached Run when a client is detached
1844 client-resized Run when a client is resized.
1846 client-session-changed Run when a client's attached session is changed.
1848 pane-died Run when the program running in a pane exits, but
1850 remain-on-exit is on so the pane has not closed.
1851 pane-exited Run when the program running in a pane exits.
1853 pane-focus-in Run when the focus enters a pane, if the
1855 focus-events option is on.
1856 pane-focus-out Run when the focus exits a pane, if the
1858 focus-events option is on.
1859 pane-set-clipboard Run when the terminal clipboard is set using the
1861 xterm(1) escape sequence.
1862 session-created Run when a new session created.
1864 session-closed Run when a session closed.
1866 session-renamed Run when a session is renamed.
1868 window-linked Run when a window is linked into a session.
1870 window-renamed Run when a window is renamed.
1872 window-unlinked Run when a window is unlinked from a session.
1874 Hooks are managed with these commands:
1876 set-hook [-gRu] [-t target-session] hook-name command
1878 Without -R, sets (or with -u unsets) hook hook-name to command.
1879 If -g is given, hook-name is added to the global list of hooks,
1880 otherwise it is added to the session hooks (for target-session
1881 with -t). Like options, session hooks inherit from the global
1882 ones.
1883 With -R, run hook-name immediately.
1885 show-hooks [-g] [-t target-session]
1887 Shows the global list of hooks with -g, otherwise the session
1888 hooks.
1889
1891 If the mouse option is on (the default is off), tmux allows mouse events
1892 to be bound as keys. The name of each key is made up of a mouse event
1893 (such as ‘MouseUp1’) and a location suffix, one of the following:
1894 Pane the contents of a pane
1896 Border a pane border
1897 Status the status line window list
1898 StatusLeft the left part of the status line
1899 StatusRight the right part of the status line
1900 StatusDefault any other part of the status line
1901 The following mouse events are available:
1903 WheelUp WheelDown
1905 MouseDown1 MouseUp1 MouseDrag1 MouseDragEnd1
1906 MouseDown2 MouseUp2 MouseDrag2 MouseDragEnd2
1907 MouseDown3 MouseUp3 MouseDrag3 MouseDragEnd3
1908 DoubleClick1 DoubleClick2 DoubleClick3
1909 TripleClick1 TripleClick2 TripleClick3
1910 Each should be suffixed with a location, for example ‘MouseDown1Status’.
1912 The special token ‘{mouse}’ or ‘=’ may be used as target-window or
1914 target-pane in commands bound to mouse key bindings. It resolves to the
1915 window or pane over which the mouse event took place (for example, the
1916 window in the status line over which button 1 was released for a
1917 ‘MouseUp1Status’ binding, or the pane over which the wheel was scrolled
1918 for a ‘WheelDownPane’ binding).
1919 The send-keys -M flag may be used to forward a mouse event to a pane.
1921 The default key bindings allow the mouse to be used to select and resize
1923 panes, to copy text and to change window using the status line. These
1924 take effect if the mouse option is turned on.
1925
1927 Certain commands accept the -F flag with a format argument. This is a
1928 string which controls the output format of the command. Replacement
1929 variables are enclosed in ‘#{’ and ‘}’, for example ‘#{session_name}’.
1930 The possible variables are listed in the table below, or the name of a
1931 tmux option may be used for an option's value. Some variables have a
1932 shorter alias such as ‘#S’; ‘##’ is replaced by a single ‘#’, ‘#,’ by a
1933 ‘,’ and ‘#}’ by a ‘}’.
1934 Conditionals are available by prefixing with ‘?’ and separating two
1936 alternatives with a comma; if the specified variable exists and is not
1937 zero, the first alternative is chosen, otherwise the second is used. For
1938 example ‘#{?session_attached,attached,not attached}’ will include the
1939 string ‘attached’ if the session is attached and the string ‘not
1940 attached’ if it is unattached, or ‘#{?automatic-rename,yes,no}’ will
1941 include ‘yes’ if automatic-rename is enabled, or ‘no’ if not. Condition‐
1942 als can be nested arbitrarily. Inside a conditional, ‘,’ and ‘}’ must be
1943 escaped as ‘#,’ and ‘#}’, unless they are part of a ‘#{...}’ replacement.
1944 For example:
1945 #{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W .
1947 Comparisons may be expressed by prefixing two comma-separated alterna‐
1949 tives by ‘==’ or ‘!=’ and a colon. For example ‘#{==:#{host},myhost}’
1950 will be replaced by ‘1’ if running on ‘myhost’, otherwise by ‘0’. An ‘m’
1951 specifies an fnmatch(3) comparison where the first argument is the pat‐
1952 tern and the second the string to compare, for example
1953 ‘#{m:*foo*,#{host}}’. ‘||’ and ‘&&’ evaluate to true if either or both
1954 of two comma-separated alternatives are true, for example
1955 ‘#{||:#{pane_in_mode},#{alternate_on}}’. A ‘C’ performs a search for an
1956 fnmatch(3) pattern in the pane content and evaluates to zero if not
1957 found, or a line number if found.
1958 A limit may be placed on the length of the resultant string by prefixing
1960 it by an ‘=’, a number and a colon. Positive numbers count from the
1961 start of the string and negative from the end, so ‘#{=5:pane_title}’ will
1962 include at most the first 5 characters of the pane title, or
1963 ‘#{=-5:pane_title}’ the last 5 characters. Prefixing a time variable
1964 with ‘t:’ will convert it to a string, so if ‘#{window_activity}’ gives
1965 ‘1445765102’, ‘#{t:window_activity}’ gives ‘Sun Oct 25 09:25:02 2015’.
1966 The ‘b:’ and ‘d:’ prefixes are basename(3) and dirname(3) of the variable
1967 respectively. ‘q:’ will escape sh(1) special characters. ‘E:’ will
1968 expand the format twice, for example ‘#{E:status-left}’ is the result of
1969 expanding the content of the status-left option rather than the content
1970 itself. ‘T:’ is like ‘E:’ but also expands strftime(3) specifiers.
1971 ‘S:’, ‘W:’ or ‘P:’ will loop over each session, window or pane and insert
1972 the format once for each. For windows and panes, two comma-separated
1973 formats may be given: the second is used for the current window or active
1974 pane. For example, to get a list of windows formatted like the status
1975 line:
1976 #{W:#{E:window-status-format} ,#{E:window-status-current-format} }
1978 A prefix of the form ‘s/foo/bar/:’ will substitute ‘foo’ with ‘bar’
1980 throughout.
1981 In addition, the first line of a shell command's output may be inserted
1983 using ‘#()’. For example, ‘#(uptime)’ will insert the system's uptime.
1984 When constructing formats, tmux does not wait for ‘#()’ commands to fin‐
1985 ish; instead, the previous result from running the same command is used,
1986 or a placeholder if the command has not been run before. If the command
1987 hasn't exited, the most recent line of output will be used, but the sta‐
1988 tus line will not be updated more than once a second. Commands are exe‐
1989 cuted with the tmux global environment set (see the ENVIRONMENT section).
1990 The following variables are available, where appropriate:
1992 Variable name Alias Replaced with
1994 alternate_on If pane is in alternate screen
1995 alternate_saved_x Saved cursor X in alternate screen
1996 alternate_saved_y Saved cursor Y in alternate screen
1997 buffer_created Time buffer created
1998 buffer_name Name of buffer
1999 buffer_sample Sample of start of buffer
2000 buffer_size Size of the specified buffer in bytes
2001 client_activity Time client last had activity
2002 client_created Time client created
2003 client_control_mode 1 if client is in control mode
2004 client_discarded Bytes discarded when client behind
2005 client_height Height of client
2006 client_key_table Current key table
2007 client_last_session Name of the client's last session
2008 client_name Name of client
2009 client_pid PID of client process
2010 client_prefix 1 if prefix key has been pressed
2011 client_readonly 1 if client is readonly
2012 client_session Name of the client's session
2013 client_termname Terminal name of client
2014 client_termtype Terminal type of client
2015 client_tty Pseudo terminal of client
2016 client_utf8 1 if client supports utf8
2017 client_width Width of client
2018 client_written Bytes written to client
2019 command Name of command in use, if any
2020 command_list_name Command name if listing commands
2021 command_list_alias Command alias if listing commands
2022 command_list_usage Command usage if listing commands
2023 cursor_flag Pane cursor flag
2024 cursor_character Character at cursor in pane
2025 cursor_x Cursor X position in pane
2026 cursor_y Cursor Y position in pane
2027 history_bytes Number of bytes in window history
2028 history_limit Maximum window history lines
2029 history_size Size of history in lines
2030 hook Name of running hook, if any
2031 hook_pane ID of pane where hook was run, if any
2032 hook_session ID of session where hook was run, if any
2033 hook_session_name Name of session where hook was run, if
2034 any
2035 hook_window ID of window where hook was run, if any
2036 hook_window_name Name of window where hook was run, if any
2037 host #H Hostname of local host
2038 host_short #h Hostname of local host (no domain name)
2039 insert_flag Pane insert flag
2040 keypad_cursor_flag Pane keypad cursor flag
2041 keypad_flag Pane keypad flag
2042 line Line number in the list
2043 mouse_any_flag Pane mouse any flag
2044 mouse_button_flag Pane mouse button flag
2045 mouse_standard_flag Pane mouse standard flag
2046 mouse_all_flag Pane mouse all flag
2047 pane_active 1 if active pane
2048 pane_at_bottom 1 if pane is at the bottom of window
2049 pane_at_left 1 if pane is at the left of window
2050 pane_at_right 1 if pane is at the right of window
2051 pane_at_top 1 if pane is at the top of window
2052 pane_bottom Bottom of pane
2053 pane_current_command Current command if available
2054 pane_current_path Current path if available
2055 pane_dead 1 if pane is dead
2056 pane_dead_status Exit status of process in dead pane
2057 pane_format 1 if format is for a pane (not assuming
2058 the current)
2059 pane_height Height of pane
2060 pane_id #D Unique pane ID
2061 pane_in_mode If pane is in a mode
2062 pane_input_off If input to pane is disabled
2063 pane_index #P Index of pane
2064 pane_left Left of pane
2065 pane_mode Name of pane mode, if any.
2066 pane_pid PID of first process in pane
2067 pane_pipe 1 if pane is being piped
2068 pane_right Right of pane
2069 pane_search_string Last search string in copy mode
2070 pane_start_command Command pane started with
2071 pane_synchronized If pane is synchronized
2072 pane_tabs Pane tab positions
2073 pane_title #T Title of pane
2074 pane_top Top of pane
2075 pane_tty Pseudo terminal of pane
2076 pane_width Width of pane
2077 pid Server PID
2078 rectangle_toggle 1 if rectangle selection is activated
2079 scroll_region_lower Bottom of scroll region in pane
2080 scroll_region_upper Top of scroll region in pane
2081 scroll_position Scroll position in copy mode
2082 selection_present 1 if selection started in copy mode
2083 session_alerts List of window indexes with alerts
2084 session_attached Number of clients session is attached to
2085 session_activity Time of session last activity
2086 session_created Time session created
2087 session_format 1 if format is for a session (not
2088 assuming the current)
2089 session_last_attached Time session last attached
2090 session_group Name of session group
2091 session_group_size Size of session group
2092 session_group_list List of sessions in group
2093 session_grouped 1 if session in a group
2094 session_id Unique session ID
2095 session_many_attached 1 if multiple clients attached
2096 session_name #S Name of session
2097 session_stack Window indexes in most recent order
2098 session_windows Number of windows in session
2099 socket_path Server socket path
2100 start_time Server start time
2101 version Server version
2102 window_activity Time of window last activity
2103 window_activity_flag 1 if window has activity
2104 window_active 1 if window active
2105 window_bell_flag 1 if window has bell
2106 window_bigger 1 if window is larger than client
2107 window_end_flag 1 if window has the highest index
2108 window_flags #F Window flags
2109 window_format 1 if format is for a window (not assuming
2110 the current)
2111 window_height Height of window
2112 window_id Unique window ID
2113 window_index #I Index of window
2114 window_last_flag 1 if window is the last used
2115 window_layout Window layout description, ignoring
2116 zoomed window panes
2117 window_linked 1 if window is linked across sessions
2118 window_name #W Name of window
2119 window_offset_x X offset into window if larger than
2120 client
2121 window_offset_y Y offset into window if larger than
2122 client
2123 window_panes Number of panes in window
2124 window_silence_flag 1 if window has silence alert
2125 window_stack_index Index in session most recent stack
2126 window_start_flag 1 if window has the lowest index
2127 window_visible_layout Window layout description, respecting
2128 zoomed window panes
2129 window_width Width of window
2130 window_zoomed_flag 1 if window is zoomed
2131 wrap_flag Pane wrap flag
2132
2134 tmux offers various options to specify the colour and attributes of
2135 aspects of the interface, for example status-style for the status line.
2136 In addition, embedded styles may be specified in format options, such as
2137 status-left-format, by enclosing them in ‘#[’ and ‘’].
2138 A style may be the single term ‘default’ to specify the default style
2140 (which may inherit from another option) or a space or comma separated
2141 list of the following:
2142 fg=colour
2144 Set the foreground colour. The colour is one of: black, red,
2145 green, yellow, blue, magenta, cyan, white; if supported the
2146 bright variants brightred, brightgreen, brightyellow; colour0 to
2147 colour255 from the 256-colour set; default for the default
2148 colour; terminal for the terminal default colour; or a hexadeci‐
2149 mal RGB string such as ‘#ffffff’.
2150 bg=colour
2152 Set the background colour.
2153 none Set no attributes (turn off any active attributes).
2155 bright (or bold), dim, underscore, blink, reverse, hidden, italics,
2157 strikethrough, double-underscore, curly-underscore,
2158 dotted-underscore, dashed-underscore
2159 Set an attribute. Any of the attributes may be prefixed with
2160 ‘no’ to unset.
2161 align=left (or noalign), align=centre, align=right
2163 Align text to the left, centre or right of the available space if
2164 appropriate.
2165 list=on, list=focus, list=left-marker, list=right=marker, nolist
2167 Mark the position of the various window list components in the
2168 status-format option: list=on marks the start of the list;
2169 list=focus is the part of the list that should be kept in focus
2170 if the entire list won't fit in the available space (typically
2171 the current window); list=left-marker and list=right-marker mark
2172 the text to be used to mark that text has been trimmed from the
2173 left or right of the list if there is not enough space.
2174 range=left, range=right, range=window|X, norange
2176 Mark a range in the status-format option. range=left and
2177 range=right are the text used for the ‘StatusLeft’ and
2178 ‘StatusRight’ mouse keys. range=window|X is the range for a win‐
2179 dow passed to the ‘Status’ mouse key, where ‘X’ is a window
2180 index.
2181 Examples are:
2183 fg=yellow bold underscore blink
2185 bg=black,fg=default,noreverse
2186
2188 tmux distinguishes between names and titles. Windows and sessions have
2189 names, which may be used to specify them in targets and are displayed in
2190 the status line and various lists: the name is the tmux identifier for a
2191 window or session. Only panes have titles. A pane's title is typically
2192 set by the program running inside the pane using an escape sequence (like
2193 it would set the xterm(1) window title in X(7)). Windows themselves do
2194 not have titles - a window's title is the title of its active pane. tmux
2195 itself may set the title of the terminal in which the client is running,
2196 see the set-titles option.
2197 A session's name is set with the new-session and rename-session commands.
2199 A window's name is set with one of:
2200 1. A command argument (such as -n for new-window or new-session).
2202 2. An escape sequence (if the allow-rename option is turned on):
2204 $ printf '\033kWINDOW_NAME\033\\'
2206 3. Automatic renaming, which sets the name to the active command in
2208 the window's active pane. See the automatic-rename option.
2209 When a pane is first created, its title is the hostname. A pane's title
2211 can be set via the title setting escape sequence, for example:
2212 $ printf '\033]2;My Title\033\\'
2214 It can also be modified with the select-pane -T command.
2216
2218 When the server is started, tmux copies the environment into the global
2219 environment; in addition, each session has a session environment. When a
2220 window is created, the session and global environments are merged. If a
2221 variable exists in both, the value from the session environment is used.
2222 The result is the initial environment passed to the new process.
2223 The update-environment session option may be used to update the session
2225 environment from the client when a new session is created or an old reat‐
2226 tached. tmux also initialises the TMUX variable with some internal
2227 information to allow commands to be executed from inside, and the TERM
2228 variable with the correct terminal setting of ‘screen’.
2229 Commands to alter and view the environment are:
2231 set-environment [-gru] [-t target-session] name [value]
2233 (alias: setenv)
2234 Set or unset an environment variable. If -g is used, the change
2235 is made in the global environment; otherwise, it is applied to
2236 the session environment for target-session. The -u flag unsets a
2237 variable. -r indicates the variable is to be removed from the
2238 environment before starting a new process.
2239 show-environment [-gs] [-t target-session] [variable]
2241 (alias: showenv)
2242 Display the environment for target-session or the global environ‐
2243 ment with -g. If variable is omitted, all variables are shown.
2244 Variables removed from the environment are prefixed with ‘-’. If
2245 -s is used, the output is formatted as a set of Bourne shell com‐
2246 mands.
2247
2249 tmux includes an optional status line which is displayed in the bottom
2250 line of each terminal.
2251 By default, the status line is enabled and one line in height (it may be
2253 disabled or made multiple lines with the status session option) and con‐
2254 tains, from left-to-right: the name of the current session in square
2255 brackets; the window list; the title of the active pane in double quotes;
2256 and the time and date.
2257 Each line of the status line is configured with the status-format option.
2259 The default is made of three parts: configurable left and right sections
2260 (which may contain dynamic content such as the time or output from a
2261 shell command, see the status-left, status-left-length, status-right, and
2262 status-right-length options below), and a central window list. By
2263 default, the window list shows the index, name and (if any) flag of the
2264 windows present in the current session in ascending numerical order. It
2265 may be customised with the window-status-format and
2266 window-status-current-format options. The flag is one of the following
2267 symbols appended to the window name:
2268 Symbol Meaning
2270 * Denotes the current window.
2271 - Marks the last window (previously selected).
2272 # Window activity is monitored and activity has been
2273 detected.
2274 ! Window bells are monitored and a bell has occurred in the
2275 window.
2276 ~ The window has been silent for the monitor-silence
2277 interval.
2278 M The window contains the marked pane.
2279 Z The window's active pane is zoomed.
2280 The # symbol relates to the monitor-activity window option. The window
2282 name is printed in inverted colours if an alert (bell, activity or
2283 silence) is present.
2284 The colour and attributes of the status line may be configured, the
2286 entire status line using the status-style session option and individual
2287 windows using the window-status-style window option.
2288 The status line is automatically refreshed at interval if it has changed,
2290 the interval may be controlled with the status-interval session option.
2291 Commands related to the status line are as follows:
2293 command-prompt [-1i] [-I inputs] [-p prompts] [-t target-client]
2295 [template]
2296 Open the command prompt in a client. This may be used from
2297 inside tmux to execute commands interactively.
2298 If template is specified, it is used as the command. If present,
2300 -I is a comma-separated list of the initial text for each prompt.
2301 If -p is given, prompts is a comma-separated list of prompts
2302 which are displayed in order; otherwise a single prompt is dis‐
2303 played, constructed from template if it is present, or ‘:’ if
2304 not.
2305 Before the command is executed, the first occurrence of the
2307 string ‘%%’ and all occurrences of ‘%1’ are replaced by the
2308 response to the first prompt, all ‘%2’ are replaced with the
2309 response to the second prompt, and so on for further prompts. Up
2310 to nine prompt responses may be replaced (‘%1’ to ‘%9’). ‘%%%’
2311 is like ‘%%’ but any quotation marks are escaped.
2312 -1 makes the prompt only accept one key press, in this case the
2314 resulting input is a single character. -i executes the command
2315 every time the prompt input changes instead of when the user
2316 exits the command prompt.
2317 The following keys have a special meaning in the command prompt,
2319 depending on the value of the status-keys option:
2320 Function vi emacs
2322 Cancel command prompt Escape Escape
2323 Delete current word C-w
2324 Delete entire command d C-u
2325 Delete from cursor to end D C-k
2326 Execute command Enter Enter
2327 Get next command from history Down
2328 Get previous command from history Up
2329 Insert top paste buffer p C-y
2330 Look for completions Tab Tab
2331 Move cursor left h Left
2332 Move cursor right l Right
2333 Move cursor to end $ C-e
2334 Move cursor to next word w M-f
2335 Move cursor to previous word b M-b
2336 Move cursor to start 0 C-a
2337 Transpose characters C-t
2338 confirm-before [-p prompt] [-t target-client] command
2340 (alias: confirm)
2341 Ask for confirmation before executing command. If -p is given,
2342 prompt is the prompt to display; otherwise a prompt is con‐
2343 structed from command. It may contain the special character
2344 sequences supported by the status-left option.
2345 This command works only from inside tmux.
2347 display-message [-apv] [-c target-client] [-t target-pane] [message]
2349 (alias: display)
2350 Display a message. If -p is given, the output is printed to std‐
2351 out, otherwise it is displayed in the target-client status line.
2352 The format of message is described in the FORMATS section; infor‐
2353 mation is taken from target-pane if -t is given, otherwise the
2354 active pane for the session attached to target-client.
2355 -v prints verbose logging as the format is parsed and -a lists
2357 the format variables and their values.
2358
2360 tmux maintains a set of named paste buffers. Each buffer may be either
2361 explicitly or automatically named. Explicitly named buffers are named
2362 when created with the set-buffer or load-buffer commands, or by renaming
2363 an automatically named buffer with set-buffer -n. Automatically named
2364 buffers are given a name such as ‘buffer0001’, ‘buffer0002’ and so on.
2365 When the buffer-limit option is reached, the oldest automatically named
2366 buffer is deleted. Explicitly named buffers are not subject to
2367 buffer-limit and may be deleted with delete-buffer command.
2368 Buffers may be added using copy-mode or the set-buffer and load-buffer
2370 commands, and pasted into a window using the paste-buffer command. If a
2371 buffer command is used and no buffer is specified, the most recently
2372 added automatically named buffer is assumed.
2373 A configurable history buffer is also maintained for each window. By
2375 default, up to 2000 lines are kept; this can be altered with the
2376 history-limit option (see the set-option command above).
2377 The buffer commands are as follows:
2379 choose-buffer [-NZ] [-F format] [-f filter] [-O sort-order] [-t
2381 target-pane] [template]
2382 Put a pane into buffer mode, where a buffer may be chosen inter‐
2383 actively from a list. -Z zooms the pane. The following keys may
2384 be used in buffer mode:
2385 Key Function
2387 Enter Paste selected buffer
2388 Up Select previous buffer
2389 Down Select next buffer
2390 C-s Search by name or content
2391 n Repeat last search
2392 t Toggle if buffer is tagged
2393 T Tag no buffers
2394 C-t Tag all buffers
2395 p Paste selected buffer
2396 P Paste tagged buffers
2397 d Delete selected buffer
2398 D Delete tagged buffers
2399 f Enter a format to filter items
2400 O Change sort order
2401 v Toggle preview
2402 q Exit mode
2403 After a buffer is chosen, ‘%%’ is replaced by the buffer name in
2405 template and the result executed as a command. If template is
2406 not given, "paste-buffer -b '%%'" is used.
2407 -O specifies the initial sort order: one of ‘time’, ‘name’ or
2409 ‘size’. -f specifies an initial filter: the filter is a format -
2410 if it evaluates to zero, the item in the list is not shown, oth‐
2411 erwise it is shown. If a filter would lead to an empty list, it
2412 is ignored. -F specifies the format for each item in the list.
2413 -N starts without the preview. This command works only if at
2414 least one client is attached.
2415 clear-history [-t target-pane]
2417 (alias: clearhist)
2418 Remove and free the history for the specified pane.
2419 delete-buffer [-b buffer-name]
2421 (alias: deleteb)
2422 Delete the buffer named buffer-name, or the most recently added
2423 automatically named buffer if not specified.
2424 list-buffers [-F format]
2426 (alias: lsb)
2427 List the global buffers. For the meaning of the -F flag, see the
2428 FORMATS section.
2429 load-buffer [-b buffer-name] path
2431 (alias: loadb)
2432 Load the contents of the specified paste buffer from path.
2433 paste-buffer [-dpr] [-b buffer-name] [-s separator] [-t target-pane]
2435 (alias: pasteb)
2436 Insert the contents of a paste buffer into the specified pane.
2437 If not specified, paste into the current one. With -d, also
2438 delete the paste buffer. When output, any linefeed (LF) charac‐
2439 ters in the paste buffer are replaced with a separator, by
2440 default carriage return (CR). A custom separator may be speci‐
2441 fied using the -s flag. The -r flag means to do no replacement
2442 (equivalent to a separator of LF). If -p is specified, paste
2443 bracket control codes are inserted around the buffer if the
2444 application has requested bracketed paste mode.
2445 save-buffer [-a] [-b buffer-name] path
2447 (alias: saveb)
2448 Save the contents of the specified paste buffer to path. The -a
2449 option appends to rather than overwriting the file.
2450 set-buffer [-a] [-b buffer-name] [-n new-buffer-name] data
2452 (alias: setb)
2453 Set the contents of the specified buffer to data. The -a option
2454 appends to rather than overwriting the buffer. The -n option
2455 renames the buffer to new-buffer-name.
2456 show-buffer [-b buffer-name]
2458 (alias: showb)
2459 Display the contents of the specified buffer.
2460
2462 Miscellaneous commands are as follows:
2463 clock-mode [-t target-pane]
2465 Display a large clock.
2466 if-shell [-bF] [-t target-pane] shell-command command [command]
2468 (alias: if)
2469 Execute the first command if shell-command returns success or the
2470 second command otherwise. Before being executed, shell-command
2471 is expanded using the rules specified in the FORMATS section,
2472 including those relevant to target-pane. With -b, shell-command
2473 is run in the background.
2474 If -F is given, shell-command is not executed but considered suc‐
2476 cess if neither empty nor zero (after formats are expanded).
2477 lock-server
2479 (alias: lock)
2480 Lock each client individually by running the command specified by
2481 the lock-command option.
2482 run-shell [-b] [-t target-pane] shell-command
2484 (alias: run)
2485 Execute shell-command in the background without creating a win‐
2486 dow. Before being executed, shell-command is expanded using the
2487 rules specified in the FORMATS section. With -b, the command is
2488 run in the background. After it finishes, any output to stdout
2489 is displayed in copy mode (in the pane specified by -t or the
2490 current pane if omitted). If the command doesn't return success,
2491 the exit status is also displayed.
2492 wait-for [-L | -S | -U] channel
2494 (alias: wait)
2495 When used without options, prevents the client from exiting until
2496 woken using wait-for -S with the same channel. When -L is used,
2497 the channel is locked and any clients that try to lock the same
2498 channel are made to wait until the channel is unlocked with
2499 wait-for -U.
2500
2502 tmux understands some unofficial extensions to terminfo(5):
2503 Cs, Cr Set the cursor colour. The first takes a single string argument
2505 and is used to set the colour; the second takes no arguments and
2506 restores the default cursor colour. If set, a sequence such as
2507 this may be used to change the cursor colour from inside tmux:
2508 $ printf '\033]12;red\033\\'
2510 Smulx Set a styled underline. The single parameter is one of: 0 for no
2512 underline, 1 for normal underline, 2 for double underline, 3 for
2513 curly underline, 4 for dotted underline and 5 for dashed under‐
2514 line.
2515 Ss, Se Set or reset the cursor style. If set, a sequence such as this
2517 may be used to change the cursor to an underline:
2518 $ printf '\033[4 q'
2520 If Se is not set, Ss with argument 0 will be used to reset the
2522 cursor style instead.
2523 Tc Indicate that the terminal supports the ‘direct colour’ RGB
2525 escape sequence (for example, \e[38;2;255;255;255m).
2526 If supported, this is used for the initialize colour escape
2528 sequence (which may be enabled by adding the ‘initc’ and ‘ccc’
2529 capabilities to the tmux [22mterminfo(5) entry).
2530 Ms Store the current buffer in the host terminal's selection (clip‐
2532 board). See the set-clipboard option above and the xterm(1) man
2533 page.
2534
2536 tmux offers a textual interface called control mode. This allows appli‐
2537 cations to communicate with tmux using a simple text-only protocol.
2538 In control mode, a client sends tmux commands or command sequences termi‐
2540 nated by newlines on standard input. Each command will produce one block
2541 of output on standard output. An output block consists of a %begin line
2542 followed by the output (which may be empty). The output block ends with
2543 a %end or %error. %begin and matching %end or %error have two arguments:
2544 an integer time (as seconds from epoch) and command number. For example:
2545 %begin 1363006971 2
2547 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
2548 %end 1363006971 2
2549 The refresh-client -C command may be used to set the size of a client in
2551 control mode.
2552 In control mode, tmux outputs notifications. A notification will never
2554 occur inside an output block.
2555 The following notifications are defined:
2557 %client-session-changed client session-id name
2559 The client is now attached to the session with ID session-id,
2560 which is named name.
2561 %exit [reason]
2563 The tmux client is exiting immediately, either because it is not
2564 attached to any session or an error occurred. If present, reason
2565 describes why the client exited.
2566 %layout-change window-id window-layout window-visible-layout window-flags
2568 The layout of a window with ID window-id changed. The new layout
2569 is window-layout. The window's visible layout is
2570 window-visible-layout and the window flags are window-flags.
2571 %output pane-id value
2573 A window pane produced output. value escapes non-printable char‐
2574 acters and backslash as octal \xxx.
2575 %pane-mode-changed pane-id
2577 The pane with ID pane-id has changed mode.
2578 %session-changed session-id name
2580 The client is now attached to the session with ID session-id,
2581 which is named name.
2582 %session-renamed name
2584 The current session was renamed to name.
2585 %session-window-changed session-id window-id
2587 The session with ID session-id changed its active window to the
2588 window with ID window-id.
2589 %sessions-changed
2591 A session was created or destroyed.
2592 %unlinked-window-add window-id
2594 The window with ID window-id was created but is not linked to the
2595 current session.
2596 %window-add window-id
2598 The window with ID window-id was linked to the current session.
2599 %window-close window-id
2601 The window with ID window-id closed.
2602 %window-pane-changed window-id pane-id
2604 The active pane in the window with ID window-id changed to the
2605 pane with ID pane-id.
2606 %window-renamed window-id name
2608 The window with ID window-id was renamed to name.
2609
2611 ~/.tmux.conf Default tmux configuration file.
2612 /etc/tmux.conf System-wide configuration file.
2613
2615 To create a new tmux session running vi(1):
2616 $ tmux new-session vi
2618 Most commands have a shorter form, known as an alias. For new-session,
2620 this is new:
2621 $ tmux new vi
2623 Alternatively, the shortest unambiguous form of a command is accepted.
2625 If there are several options, they are listed:
2626 $ tmux n
2628 ambiguous command: n, could be: new-session, new-window, next-window
2629 Within an active session, a new window may be created by typing ‘C-b c’
2631 (Ctrl followed by the ‘b’ key followed by the ‘c’ key).
2632 Windows may be navigated with: ‘C-b 0’ (to select window 0), ‘C-b 1’ (to
2634 select window 1), and so on; ‘C-b n’ to select the next window; and ‘C-b
2635 p’ to select the previous window.
2636 A session may be detached using ‘C-b d’ (or by an external event such as
2638 ssh(1) disconnection) and reattached with:
2639 $ tmux attach-session
2641 Typing ‘C-b ?’ lists the current key bindings in the current window; up
2643 and down may be used to navigate the list or ‘q’ to exit from it.
2644 Commands to be run when the tmux server is started may be placed in the
2646 ~/.tmux.conf configuration file. Common examples include:
2647 Changing the default prefix key:
2649 set-option -g prefix C-a
2651 unbind-key C-b
2652 bind-key C-a send-prefix
2653 Turning the status line off, or changing its colour:
2655 set-option -g status off
2657 set-option -g status-style bg=blue
2658 Setting other options, such as the default command, or locking after 30
2660 minutes of inactivity:
2661 set-option -g default-command "exec /bin/ksh"
2663 set-option -g lock-after-time 1800
2664 Creating new key bindings:
2666 bind-key b set-option status
2668 bind-key / command-prompt "split-window 'exec man %%'"
2669 bind-key S command-prompt "new-window -n %1 'ssh %1'"
2670
2672 pty(4)
2673
2675 Nicholas Marriott <nicholas.marriott@gmail.com>
2676BSD June 20, 2019 BSD