Skip to content

Getting Started

Nicholas Marriott edited this page Mar 30, 2020 · 71 revisions

Getting started

About tmux

tmux is a program which runs in a terminal and allows multiple other terminal programs to be run inside it. Each program inside tmux gets its own terminal managed by tmux, which can be accessed from the single terminal where tmux is running - this called multiplexing and tmux is a terminal multiplexer.

tmux - and any programs running inside it - may be detached from the terminal where it is running (the outside terminal) and and later reattached to the same or another terminal.

Programs run inside tmux may be full screen interactive programs like vi(1) or top(1), shells like bash(1) or ksh(1), or any other program that can be run in a Unix terminal.

There is a powerful feature set to access, manage and organize programs inside tmux, both interactively and from scripts.

The main uses of tmux are to:

  • Protect running programs on a remote server from connection drops by running them inside tmux.

  • Allow programs running on a remote server to be accessed from multiple different local computers.

  • Work with multiple programs and shells together in one terminal, a bit like a window manager.

For example:

  • A user connects to a remote server using ssh(1) from an xterm(1) on their work computer and run several programs. perhaps an editor, a compiler and a few shells.

  • They work with these programs interactively, perhaps start compiling, then close the xterm(1) with tmux and go home for the day.

  • They are then able to connect to the same remote server from home, attach to tmux, and continue from where they were previously.

Here is a screenshot of tmux in an xterm(1) showing the shell:

About this document

This document gives an overview of some of tmux's key concepts, a description of how to use the main features interactively and some information on basic customization and configuration.

Note that this document may mention features only available in the latest tmux release. Only the latest tmux release is supported. Releases are made approximately every six months.

tmux may be installed from package management systems on most major platforms. See this document for instructions on how to install tmux or how to build it from source.

Other documentation and help

Here are several places to find documentation and help about tmux:

Basic concepts

tmux has a set of basic concepts and terms with which it is important to be familiar. This section gives a description of how the terminals inside tmux are grouped together and the various terms tmux uses.

The tmux server and clients

tmux keeps all its state in a single main process, called the tmux server. This runs in the background and manages all the programs running inside tmux and keeps track of their output. The tmux server is started automatically when the user runs a tmux command and by default exits when there are no running programs.

Users attach to the tmux server by starting a client. This takes over the terminal where it is run and talks to the server using a socket file in /tmp. Each client runs in one terminal, which may be an X(7) terminal such as xterm(1), the system console, or a terminal inside another program (such as tmux itself). Each client is identified by the name of the outside terminal where it is started, for example /dev/ttypf.

Sessions, windows and panes

Every terminal inside tmux belongs to one pane, this is a rectangular area which shows the content of the terminal inside tmux. Because each terminal inside tmux is shown in only one pane, the term pane can be used to mean all of the pane, the terminal and the program running inside it. The screenshot to the right shows tmux with panes.

Each pane appears in one window. A window is made up of one or more panes which together cover its entire area - so multiple panes may be visible at the same time. A window normally takes up the whole of the terminal where tmux is attached, but it can be bigger or smaller. The sizes and positions of all the panes in a window is called the window layout.

Every window has a name - by default tmux will choose one but it can be changed by the user. Window names do not have to be unique, windows are usually identified by the session and the window index rather than their name.

Each pane is separated from the panes around it by a line, this is called the pane border. There is one pane in each window called the active pane, this is where any text typed is sent and is the default pane used for commands that target the window. The pane border of the active pane is marked in green, or if there are only two panes then the top, bottom, left or right half of the border is green.

Multiple windows are grouped together into sessions. If a window is part of a session, it is said to be linked to that session. Windows may be linked to multiple sessions at the same time, although mostly they are only in one. Each window in a session has a number, called the window index - the same window may be linked at different indexes in different sessions. A session's window list is all the windows linked to that session in order of their indexes.

Each session has one current window, this is the window displayed when the session is attached and is the default window for any commands that target the session. If the current window is changed, the previous current window becomes known as the last window.

A session may be attached to one or more clients, which means it is shown on the outside terminal where that client is running. Any text typed into that outside terminal is sent to the active pane in the current window of the attached session. Sessions do not have an index but they do have a name, which must be unique.

In summary:

  • Programs run in terminals in panes, which each belong to one window.
  • Each window has a name and one active pane.
  • Windows are linked to one or more sessions.
  • Each session has a list of windows, each with an index.
  • One of the windows in a session is the current window.
  • Sessions are attached to zero or more clients.
  • Each client is attached to one session.

Summary of terms

Term Description
Client Attaches a tmux session from an outside terminal such as xterm(1)
Session Groups one or more windows together
Window Groups one or more panes together, linked to one or more sessions
Pane Contains a terminal and running program, appears in one window
Active pane The pane in the current window where typing is sent; one per window
Current window The window in the attached session where typing is sent; one per session
Last window The previous current window
Session name The name of a session, defaults to a number starting from zero
Window list The list of windows in a session in order by number
Window name The name of a window, defaults to the name of the running program in the active pane
Window index The number of a window in a session's window list
Window layout The size and position of the panes in a window

Using tmux interactively

Creating sessions

To create the first tmux session, run tmux from the shell. A new session is created using the new-session command - new for short:

$ tmux new

Without arguments, new-session creates a new session and attaches it. Because this is the first session, the tmux server is started and the tmux run from the shell becomes the first client and attaches to it.

The new session will have one window (at index 0) with a single pane containing a shell. The shell prompt should appear at the top of the terminal and the green status line at the bottom (more on the status line is below).

By default, the first session will be called 0, the second 1 and so on. new-session allows a name to be specified for the session with the -s flag:

$ tmux new -smysession

This creates a new session called mysession. A command may be given instead of running a shell by passing additional arguments. If one argument is given, tmux will pass it to the shell, if more than one it runs the command directly. For example these run emacs(1):

$ tmux new 'emacs ~/.tmux.conf'

Or:

$ tmux new -- emacs ~/.tmux.conf

By default, tmux calls the first window in the session after whatever is running in it. The -n flag gives a name to use instead, in this case a window mytopwindow running top(1):

$ tmux new -nmytopwindow top

new-session has other flags - some are covered below. A full list is in the tmux manual.

The status line

When a tmux client is attached, it shows a status line on the bottom line of the screen. By default this is green and shows:

  • On the left, the name of the attached session: [0].

  • In the middle, a list of the windows in the session, with their index, for example with one window called ksh at index 0: 0:ksh.

  • On the right, the pane title in quotes (this defaults to the name of the host running tmux) and the time and the date.

As new windows are opened, the window list grows - if there are too many windows to fit on the width of the terminal, a < or > will be added at the left or right or both to show there are hidden windows.

In the window list, the current window is marked with a * after the name, and the last window with a -.

The prefix key

Once a tmux client is attached, any keys entered are forwarded to the program running in the active pane of the current window. For keys that control tmux itself, a special key must be pressed first - this is called the prefix key.

The default prefix key is C-b, which means the Ctrl key and b. In tmux, modifier keys are shown by prefixing a key with C- for the control key, M- for the meta key (normally Alt on modern computers) and S- for the shift key. These may be combined together, so C-M-x means pressing the control key, meta key and x together.

When the prefix key is pressed, tmux waits for another key press and that determines what tmux command is executed. Keys like this are shown here with a space between them: C-b c means first the prefix key C-b is pressed, then it is released and then the c key is pressed. Care must be taken to release the Ctrl key after pressing C-b if necessary - C-b c is different from C-b C-c.

Pressing C-b twice sends the C-b key to the program running in the active pane.

Help keys

Every default tmux key binding has a short description to help remember what the key does. A list of all the keys can be seen by pressing C-b ?.

C-b ? enters view mode to show text. A pane in view mode has its own key bindings which do not need the prefix key. These broadly follow emacs(1). The most important are Up, Down, C-Up, C-Down to scroll up and down, and q to exit the mode. The line number of the top visible line together with the total number of lines is shown in the top right.

Alternatively, the same list can be seen from the shell by running:

$ tmux lsk -N|more

C-b / shows the description of a single key - a prompt at the bottom of the terminal appears. Pressing a key will show its description in the same place. For example, pressing C-b / then ? shows:

C-b ? List key bindings

Commands and flags

tmux has a large set of commands. These all have a name like new-window or new-session or list-keys and many also have a shorter alias like neww or new or lsk.

Any time a key binding is used, it runs one or more tmux commands. For example, C-b c runs the new-window command.

Commands can also be used from the shell, as with new-session and list-keys above.

Each command has zero or more flags, in the same way as standard Unix commands. Flags may or may not take a single argument themselves. In addition, commands may take additional arguments after the flags. Flags are passed after the command, for example to run the new-session command (alias new) with flags -d and -n:

$ tmux new-session -d -nmysession

All commands and their flags are documented in the tmux manual page.

This document focuses on the available key bindings, but commands are mentioned for information or where there is a useful flag. They can be entered from the shell or from the command prompt, described in the next section.

The command prompt

tmux has an interactive command prompt. This can be opened by pressing C-b : and appears instead of the status line, as shown in this screenshot.

At the prompt, commands can be entered similarly to how they are at the shell. Output will either be shown for a short period in the status line, or switch the active pane into view mode.

By default, the command prompt uses keys similar to emacs(1); however, if the VISUAL or EDITOR environment variables are set to something containing vi (such as vi or vim or nvi), then vi(1)-style keys are used instead.

Attaching and detaching

Detaching from tmux means that the client exits and detaches from the outside terminal, returning to the shell and leaving the tmux session and any programs inside it running in the background. To detach tmux, use the C-b d key binding. When tmux detaches, it will print a message with the session name:

[detached (from session mysession)]

The attach-session command attaches to an existing session. Without arguments, it will attach to the most recently used session that is not already attached:

$ tmux attach

Or -t gives the name of a session to attach to:

$ tmux attach -tmysession

By default, attaching to a session does not detach any other clients attached to the same session. To do this, add the -d flag:

$ tmux attach -dtmysession

The new-session command has a -A flag to attach to an existing session if it exists, or create a new one if it does not. For a session named mysession:

$ tmux new -Asmysession

The -D flag may be added to make new-session also behave like attach-session with -d and detach any other clients attached to the session.

Listing sessions

The list-session command (alias ls) shows a list of available sessions that can be attached. This shows four sessions called 1, 2, myothersession and mysession:

$ tmux ls
1: 3 windows (created Sat Feb 22 11:44:51 2020)
2: 1 windows (created Sat Feb 22 11:44:51 2020)
myothersession: 2 windows (created Sat Feb 22 11:44:51 2020)
mysession: 1 windows (created Sat Feb 22 11:44:51 2020)

Killing tmux entirely

If there are no sessions, windows or panes inside tmux, the server will exit. It can also be entirely killed using the kill-server command. For example, at the command prompt:

:kill-server

Creating new windows

A new window can be created in an attached session with the C-b c key binding which runs the new-window command. The new window is created at the first available index - so the second window will have index 1. The new window becomes the current window of the session.

If there are any gaps in the window list, they are filled by new windows. So if there are windows with indexes 0 and 2, the next new window will be created as index 1.

The new-window command has some useful flags which can be used with the command prompt:

  • The -d flag creates the window, but does not make it the current window.

  • -n allows a name for the new window to be given. For example using the command prompt to create a window called mynewwindow without making it the current window:

    :neww -dnmynewwindow
    
  • The -t flag specifies a target for the window. Command targets have a special syntax, but for simple use with new-window it is enough just to give a window index. This creates a window at index 999:

    :neww -t999
    

A command to be run in the new window may be given to new-window in the same way as new-session. For example to create a new window running top(1):

:neww top

Splitting the window

A pane is created by splitting a window. This is done with the split-window command which is bound to two keys by default:

  • C-b % splits the current pane into two horizontally, producing two panes next to each other, one on the left and one on the right.

  • C-b " splits the current pane into two vertically, producing two panes one above the other.

Each time a pane is split into two, each of those panes may be split again using the same key bindings, until the pane becomes too small.

split-window has several useful flags:

  • -h does a horizontal split and -v a vertical split.

  • -d does not change the active pane to the newly created pane.

  • -f makes a new pane spanning the whole width or height of the window instead of being constrained to the size of the pane being split.

  • -b puts the new pane to the left or above of the pane being split instead of to the right or below.

A command to be run in the new pane may be given to split-window in the same way as new-session and new-window.

Changing the current window

There are several key bindings to change the current window of a session:

  • C-b 0 changes to window 0, C-b 1 to window 1, up to window C-b 9 for window 9.

  • C-b ' prompts for a window index and changes to that window.

  • C-b n changes to the next window in the window list by number. So pressing C-b n when in window 1 will change to window 2 if it exists.

  • C-b p changes to the previous window in the window list by number.

  • C-b l changes to the last window, which is the window that was last the current window before the window that is now.

These are all variations of the select-window command.

Changing the active pane

The active pane can be changed between the panes in a window with these key bindings:

  • C-b Up, C-b Down, C-b Left and C-b Right change to the pane above, below, left or right of the active pane. These keys wrap around the window, so pressing C-b Down on a pane at the bottom will change to a pane at the top.
  • C-b q prints the pane numbers and their sizes on top of the panes for a short time. Pressing one of the number keys before they disappear changes the active pane to the chosen pane, so C-b q 1 will change to pane number 1.

  • C-b o moves to the next pane by pane number and C-b C-o swaps that pane with the active pane, so they exchange positions and sizes in the window.

These use the select-pane and display-panes commands.

Pane numbers are not fixed, instead panes are numbered by their position in the window, so if the pane with number 0 is swapped with the pane with number 1, the numbers are swapped as well as the panes themselves.

Choosing sessions, windows and panes

tmux includes a mode where sessions, windows or panes can be chosen from a tree, this is called tree mode. It can be used browse sessions, windows and panes; to change the attached session, the current window or active pane; to kill sessions, windows and panes; or apply a command to several at once by tagging them.

There are two key bindings to enter tree mode: C-b s starts showing only sessions and with the attached session selected; C-b w starts with sessions expanded so windows are shown and with the current window in the attached session selected.

Tree mode splits the window into two sections: the top half has a tree of sessions, windows and panes and the bottom half has a preview of the area around the cursor in each pane. For sessions the preview shows the active panes in as many windows will fit; for windows as many panes as will fit; and for panes only the selected pane.

Keys to control tree mode do not require the prefix. The list may be navigated with the Up and Down keys. Enter changes to the selected item (it becomes the attached session, current window or active pane) and exits the mode. Right expands the item if possible - sessions expand to show their windows and windows to show their panes. Left collapses the item to hide any windows or panes. O changes the order of the items and q exits tree mode.

Items in the tree are tagged by pressing t and untagged by pressing t again. Tagged items are shown in bold and with * after their name. All tagged items may be untagged by pressing T. Tagged items may be killed together by pressing X, or a command applied to them all by pressing : for a prompt.

Each item in the tree has as shortcut key in brackets at the start of the line. Pressing this key will immediately choose that item (as if it had been selected and Enter pressed). The first ten items are keys 0 to 9 and after that keys M-a to M-z are used.

This is a list of the keys available in tree mode without pressing the prefix key:

Key Function
Enter Change the attached session, current window or active pane
Up Select previous item
Down Select next item
Right Expand item
Left Collapse item
x Kill selected item
X Kill tagged items
< Scroll preview left
> Scroll preview right
C-s Search by name
n Repeat last search
t Toggle if item is tagged
T Tag no items
C-t Tag all items
: Prompt for a command to run for the selected item or each tagged item
O Change sort field
r Reverse sort order
v Toggle preview
q Exit tree mode

Tree mode is activated with the choose-tree command.

Detaching other clients

A list of clients is available by pressing C-b D (that is, C-b S-d). This is similar to tree mode and is called client mode.

Each client is shown in the list in the top half with its name, attached session, size and the time and date when it was last used; the bottom half has a preview of the selected client with as much of its status line as will fit.

The movement and tag keys are the same as tree mode, but others are different, for example the Enter key detaches the selected client.

This is a list of the keys in client mode without the movement and tagging keys that are the same as tree mode:

Key Function
Enter Detach selected client
d Detach selected client, same as Enter
D Detach tagged clients
x Detach selected client and try to kill the shell it was started from
X Detach tagged clients and try to kill the shell they were started from

Other than using client mode, the detach-client flag has a -a flag to detach all clients other than the attached client.

Killing a session, window or pane

Pressing C-b & prompts for confirmation then kills (closes) the current window. All panes in the window are killed at the same time. C-b x kills only the active pane. These are bound to the kill-window and kill-pane commands.

The kill-session command kills the attached session and all its windows and detaches the client. There is no key binding for kill-session but it can be used from the command prompt or the : prompt in tree mode.

Renaming sessions and windows

C-b $ will prompt for a new name for the attached session. This uses the rename-session command. Likewise, C-b , prompts for a new name for the current window, using the rename-window command.

Swapping and moving

tmux allows panes and windows to be swapped with the swap-pane and swap-window commands.

To make swapping easy, a single pane can be marked. There is one marked pane across all sessions. The C-b m key binding toggles whether the active pane in the current window in the attached session is the marked pane. C-b M clears the marked pane entirely. The marked pane is shown by a green background to its border and the window containing the marked pane has an M flag in the status line.

Once a pane is marked, it can be swapped with the active pane in the current window with the swap-pane command, or the window containing the marked pane can be swapped with the current window using the swap-window command. For example, using the command prompt:

:swap-pane

Panes can additionally be swapped with the pane above or below using the C-b { and C-b } key bindings.

Moving windows uses the move-window command or the C-b . key binding. Pressing C-b . will prompt for a new index for the current window. If a window already exists at the given index, an error will be shown. An existing window can be replaced by using the -k flag - to move a window to index 999:

:move-window -kt999

If there are gaps in the window list, the indexes can be renumbered with the -r flag to move-window. For example, this will change a window list of 0, 1, 3, 999 into 0, 1, 2, 3:

:movew -r

Resizing and zooming panes

Panes may be resized in small steps with C-b C-Left, C-b C-Right, C-b C-Up and C-b C-Down and in larger steps with C-b M-Left, C-b M-Right, C-b M-Up and C-b M-Down. These use the resize-pane command.

A single pane may be temporarily made to take up the whole window with C-b Z; pressing C-b Z again puts the window back where it was. This is called zooming and unzooming. A window where a pane has been zoomed is marked with a Z in the status line. Commands that change the size or position of panes in a window automatically unzoom the window.

Window layouts

The panes in a window may be automatically arranged into one of several named layouts, these may be rotated between with the C-b Space key binding or chosen directly with C-b M-1, C-b M-2 and so on.

The available layouts are:

Name Key Description
even-horizontal C-b M-1 Spread out evenly across
even-vertical C-b M-2 Spread out evenly up and down
main-horizontal C-b M-3 One large pane at the top, the rest spread out evenly across
main-vertical C-b M-4 One large pane on the left, the rest spread out evenly up and down
tiled C-b M-5 Tiled in the same number of rows as columns

Copy and paste

tmux has its own copy and paste system. A piece of copied text is called a paste buffer. Text is copied using copy mode, entered with C-b [, and the most recently copied text is pasted into the active pane with C-b ].

Paste buffers can be given names but by default they are assigned a name by tmux, such as buffer0 or buffer1. Buffers like this are called automatic buffers and at most 50 are kept - once there are 50 buffers, the oldest is removed when another is added. If a buffer is given a name, it is called a named buffer; named buffers are not deleted no matter how many there are.

Copy mode freezes any output in a pane and allows text to be copied. View mode (described earlier) is a read-only form of copy mode.

Like the command prompt, copy mode uses keys similar to emacs(1); however, if the VISUAL or EDITOR environment variables are set to something containing vi, then vi(1)-style keys are used instead. The following keys are some of those available in copy mode:

Key Action
Up, Down, Left, Right Move the cursor
C-Space Start a selection
C-w Copy the selection and exit copy mode
q Exit copy mode
C-g Stop selecting without copying, or stop searching
C-a Move the cursor to the start of the line
C-e Move the cursor to the end of the line
C-r Search interactively backwards
M-f Move the cursor to the next word
M-b Move the cursor to the previous word

Once some text is copied, the most recent may be pasted with C-b ] or an older buffer pasted by using buffer mode, entered with C-b =. Buffer mode is similar to client mode and tree mode and offers a list of buffers together with a preview of their contents. As well as the navigation and tagging keys used in tree mode and client mode, buffer mode supports the following keys:

Key Function
Enter Paste selected buffer
p Paste selected buffer, same as Enter
P Paste tagged buffers
d Delete selected buffer
D Delete tagged buffers

A buffer may be renamed using the set-buffer command. The -b flag gives the existing buffer name and -n the new name. This converts it into a named buffer. For example, to rename buffer0 to mybuffer from the command prompt:

:setb -bbuffer0 -nmybuffer

set-buffer can also be used to create buffers. To create a buffer called foo with text bar:

:setb -bfoo bar

load-buffer will load a buffer from a file:

:loadb -bbuffername ~/a/file

set-buffer or load-buffer without -b creates an automatic buffer.

An existing buffer can be saved to a file with save-buffer:

:saveb -bbuffer0 ~/saved_buffer

Finding windows and panes

C-b f prompts for some text and then enters tree mode with a filter to show only panes where that text appears in the visible content or title of the pane or in the window name. If panes are found, only those panes appear in the tree, and the text filter: active is shown above the preview. If no panes are found, all panes are shown in the tree and the text filter: no matches appears above the preview.

Using the mouse

tmux has rich support for the mouse. It can be used to change the active pane or window, to resize panes, to copy text, or to choose items from menus.

Support for the mouse is enabled with the mouse option; options and the configuration file are described in detail in the next section. To turn the mouse on from the command prompt, use the set-option command:

:set -g mouse on

Once the mouse is enabled:

  • Pressing the left button on a pane will make that pane the active pane.

  • Pressing the left button on a window name on the status line will make that the current window.

  • Dragging with the left button on a pane border resizes the pane.

  • Dragging with the left button inside a pane selects text; the selected text is copied when the mouse is released.

  • Pressing the right button on a pane opens a menu with various commands. When the mouse button is released, the selected command is run with the pane as target. Each menu item also has a key shortcut shown in brackets.

  • Pressing the right button on a window or on the session name on the status line opens a similar menu for the window or session.

Configuring tmux

The configuration file

When the tmux server is started, tmux runs a file called .tmux.conf in the user's home directory. This file contains a list of tmux commands which are executed in order. It is important to note that .tmux.conf is only run when the server is started, not when a new session is created.

A different configuration file may be run from .tmux.conf or from a running tmux server using the source-file command, for example to run .tmux.conf again from a running server using the command prompt:

:source ~/.tmux.conf

Commands in a configuration file appear one per line. Any lines starting with # are comments and are ignored:

# This is a comment - the command below turns the status line off
set -g status off

Key bindings

tmux key bindings are changed using the bind-key and unbind-key commands. Key bindings in tmux appear in key tables - there are two default key tables:

  • The root table contains key bindings for keys pressed without the prefix key.

  • The prefix table contains key bindings for keys pressed after the prefix key, like those mentioned so far in this document.

All the key bindings or those for a single table can be listed with the list-keys command. By default, this shows the keys as a series of bind-key commands. The -T flag gives the key table to show and the -N flag shows the key help, like the C-b ? key binding.

For example to list only keys in the prefix table:

$ tmux lsk -Tprefix
bind-key    -T prefix C-b     send-prefix
bind-key    -T prefix C-o     rotate-window
...

Or:

$ tmux lsk -Tprefix -N
C-b     Send the prefix key
C-o     Rotate through the panes
...

bind-key commands can be used to set a key binding, either interactively or most commonly from the configuration file. Like list-keys, bind-key has a -T flag for the key table to use. If -T is not given, the key is put in the prefix table; the -n flag is a shorthand for -Troot to use the root table.

For example, the list-keys command shows that C-b 9 changes to window 9 using the select-window command:

$ tmux lsk -Tprefix 9
bind-key -T prefix 9 select-window -t :=9

A similar key binding to make C-b M-0 change to window 10 can be added like this:

bind M-0 selectw -t:=10

The -t flag to select-window specifies the target window. In this example, the : means the target is a window and = means the name must match 10 exactly. Targets are documented further in the COMMANDS section of the manual page.

The unbind-key command removes a key binding. Like bind-key it has -T and -n flags for the key table. It is not necessary to remove a key binding before binding it again, bind-key will replace any existing key binding. unbind-key is necessary only to completely remove a key binding:

unbind M-0

Types of option

tmux is configured by setting options. There are several types of options:

  • Server options which affect the entire server.

  • Session options which affect one or all sessions.

  • Window options which affect one or all windows.

  • Pane options which affect one or all panes.

  • User options which are not used by tmux but are reserved for the user.

Session and window options have both a global set of options and a set for each session or window. If the option is not present in the session or window set, the global option is used. Pane options are similar except the window options are also checked.

When configuring tmux, it is most common to set server options and global session or window options. This document only covers these.

Showing options

Options are displayed using the show-options command. The -g flag shows global options. It can show server, session or window options:

  • -s shows server options:
$ tmux show -s
backspace C-?
buffer-limit 50
...
  • With no other flags, -g shows global session options:
$ tmux show -g
activity-action other
assume-paste-time 1
...
  • With -w it shows global window options:
$ tmux show -wg
aggressive-resize off
allow-rename off
...

An individual option value may be shown by giving its name to show-option. When an option name is given, it is not necessary to give -s or -w because tmux can work it out from the option name. For example, to show the status option:

$ tmux show -g status
status on

Changing options

Options are set or unset using the set-option command. Like show-option, it is not necessary to give -s or -w because tmux can work out it out from the option name. -g is necessary to set global session or window options; for server options it does nothing.

To set the status option:

set -g status off

Or the default-terminal option:

set -s default-terminal 'tmux-256color'

The -u flag unsets an option. Unsetting a global option restores it to its default value, for example:

set -gu status

Formats

Many options make use of formats. Formats provide a powerful syntax to configure how text appears, based on various attributes of the tmux server, a session, window or pane. Formats are enclosed in #{} in string options or as a single uppercase letter like #F. This is the default status-right with several formats:

$ tmux show -s status-right
status-right "#{?window_bigger,[#{window_offset_x}#,#{window_offset_y}] ,}\"#{=21:pane_title}\" %H:%M %d-%b-%y"

Formats are described in this document and in the manual page.

Colours and styles

tmux allows the colour and attribute of text to be configured with a simple syntax, this is known as the style. There are two places styles appear:

  • In options, such as status-style.

  • Enclosed in string options in #[], this is called an embedded style.

A style has a number of terms separated by spaces or commas, the most useful are:

  • default uses the default colour; this must appear on its own.

  • bg sets the background colour. The colour is also given, for example bg=red.

  • fg sets the foreground colour. Like bg, the colour is given: fg=green.

  • bright or bold, underscore, reverse, italics set the attributes. These appear alone, such as: bright,reverse.

Colours may be one of black, red, green, yellow, blue, magenta, cyan, white for the standard terminal colours; brightred, brightyellow and so on for the bright variants; colour0 to colour255 for the colours from the 256-colour palette; default for the default colour; or a hexadecimal RGB colour such as #882244.

The remaining style terms are described in the manual page.

For example, to set the status line background to blue using the status-style option:

set -g status-style 'bg=blue'

List of useful options

This is a short list of the most commonly used tmux options, apart from style options:

Option Type Description
base-index session If set, then windows indexes start from this instead of from 0
buffer-limit server The maximum number of automatic buffers to keep, the default is 50
default-terminal server The default value of the TERM environment variable inside tmux
display-panes-time window The time in milliseconds the pane numbers are shown for C-b q
display-time session The time in milliseconds for which messages on the status line are shown
escape-time server The time tmux waits after receiving an Escape key to see if it is part of a longer key sequence
focus-events server Whether focus key sequences are sent by tmux when the active pane changes and when received from the outside terminal if it supports them
history-limit session The maximum number of lines kept in the history for each pane
mode-keys window Whether emacs(1) or vi(1) key bindings are used in copy mode
mouse session If the mouse is enabled
pane-border-status window Whether a status line appears in every pane border: top or bottom
prefix session The prefix key, the default is C-b
remain-on-exit window Whether panes are automatically killed when the program running in the exits
renumber-windows session If on, windows are automatically renumbered to close any gaps in the window list
set-clipboard server Whether tmux should attempt to set the external X(7) clipboard when text is copied and if the outside terminal supports it
set-titles session If on, tmux will set the title of the outside terminal
status session Whether the status line if visible
status-keys session Whether emacs(1) or vi(1) key bindings are used at the command prompt
status-interval session The maximum time in seconds before the status line is redrawn
status-position session The position of the status line: top or bottom
synchronize-panes window If on, typing in any pane in the window is sent to all panes in the window - care should be taken with this option!
terminal-overrides server Any capabilities tmux should override from the TERM given for the outside terminal

List of style and format options

This is a list of the most commonly used tmux style and format options:

Option Type Description
display-panes-active-colour session The style of the active pane number for C-b q
display-panes-colour session The style of the pane numbers, apart from the active pane forC-b q
message-style session The style of messages shown on the status line
mode-style window The style of the selection in copy mode
pane-active-border-style window The style of the active pane border
pane-border-format window The format of text that appears in the pane border status line if pane-border-status is set
pane-border-style window The style of the pane borders, apart from the active pane
status-left-length session The maximum length of the status line left
status-left-style session The style of the status line left
status-left session The format of the text in the status line left
status-right-length session The maximum length of the status line right
status-right-style session The style of the status line right
status-right session The format of the text in the status line right
status-style session The style of the status line as a whole, parts may be overridden by more specific options like status-left-style
window-active-style window The style of the default colour in the active pane in the window
window-status-current-format window The format of the current window in the window list
window-status-current-style window The style of the current window in the window list
window-status-format window The format of windows in the window list, apart from the current window
window-status-separator window The separator between windows in the window list
window-status-style window The style of windows in the window list, apart from the current window
window-style window The style of the default colour of panes in the window, apart from the active pane

Common configuration changes

This section shows examples of some common configuration requests for .tmux.conf.

Changing the prefix key

The prefix key is set by the prefix option. The C-b key is also bound to the send-prefix command in the prefix key table so pressing C-b twice sends it through to the active pane. To change to C-a:

set -g prefix C-a
unbind C-b
bind C-a send-prefix

Customizing the status line

There are many options for customizing the status line. The simplest options are:

  • Turn the status line off: set -g status off

  • Move it to the top: set -g status-position top

  • Set the background colour to red: set -g status-style bg=red

  • Change the text on the right to the time only: set -g status-right '%H:%M'

  • Underline the current window: set -g window-status-current-style 'underscore'

Configuring the pane border

The pane border colours may be set:

set -g pane-border-style fg=red
set -g pane-active-border-style 'fg=red,bg=yellow'

Each pane may be given a status line with the pane-border-status option, for example to show the pane title in bold:

set -g pane-border-status top
set -g pane-border-format '#[bold]#{pane_title}#[default]'

vi(1) key bindings

tmux supports key bindings based on vi(1) for copy mode and the command prompt. This document assumes that the default emacs(1) bindings are in use. There are two options that set the key bindings:

  1. mode-keys sets the key bindings for copy mode. If this is set to vi, then the copy-mode-vi key table is used in copy mode; otherwise the copy-mode key table is used.

  2. status-keys sets the key bindings for the command prompt.

If either of the VISUAL or EDITOR environment variables are set to something containing vi (such as vi, vim, nvi) when the tmux server is first started, both of these options are set to vi.

To set both to use vi(1) keys:

set -g mode-keys vi
set -g status-keys vi

Mouse copying behaviour

When dragging the mouse to copy text, tmux copies and exits copy mode when the mouse button is released. Alternative behaviours are configured by changing the MouseDragEnd1Pane key binding. The three most useful are:

  1. Do not copy or clear the selection or exit copy mode when the mouse is released. The keyboard must be used to copy the selection:
unbind -Tcopy-mode MouseDragEnd1Pane
  1. Copy and clear the selection but do not exit copy mode:
bind -Tcopy-mode MouseDragEnd1Pane send -X copy-selection
  1. Copy but do not clear the selection:
bind -Tcopy-mode MouseDragEnd1Pane send -X copy-selection-no-clear

Other features

tmux has a large set of features and commands not mentioned in this document, many allowing powerful scripting. Here is a list of some that may be worth further reading:

  • Alerts: monitor-activity, monitor-bell, monitor-silence, activity-action, bell-action and other options.

  • Options for individual session, windows and panes.

  • Moving panes with join-pane and break-pane.

  • Sending keys to panes with send-keys.

  • The command prompt history-file option.

  • Saved layout strings with select-layout.

  • Command sequences: select-window; kill-window.

  • Configuration file syntax: {}, %if and so on.

  • Mouse key bindings: MouseDown1Pane and so on.

  • Locking: lock-command, lock-after-time and other options.

  • Capturing pane content with capture-pane and piping with pipe-pane.

  • Linking windows: the link-window command.

  • Session groups: the -t flag to new-session.

  • Respawing window and panes with respawn-window and respawn-pane.

  • Custom menus with the display-menu command and custom prompts with command-prompt and confirm-before.

  • Different key tables: bind-key and the -T flag to switch-client.

  • Empty panes: the split-window with an empty command and -I to display-message.

  • Hooks: set-hook and show-hooks.

  • Synchronization for scripts with wait-for.

You can’t perform that action at this time.