PLEASE NOTE: most display problems are due to incorrect TERM! Before
reporting problems make SURE that TERM settings are correct inside and
outside tmux.

Inside tmux TERM must be "screen", "tmux" or similar (such as "tmux-256color").
Don't bother reporting problems where it isn't!

Outside, it should match your terminal: particularly, use "rxvt" for rxvt
and derivatives.

The environment variable TERM tells applications the name of a terminal description to read from the terminfo(5) database. Each description consists of a number of named capabilities which tell applications what to send to control the terminal. For example, the cup capability contains the escape sequence used to move the cursor up.

It is important that TERM points to the correct description for the terminal an application is running in - if it doesn't, applications may misbehave.

The infocmp(1) command shows the contents of a terminal description and the tic(1) command builds and installs a description from a file (the -x flag is normally required with both).

Check the latest version of tmux from Git to see if the problem is still present.

Please send bug reports by email to [email protected] or [email protected] or by opening a GitHub issue. Please see the CONTRIBUTING file for information on what to include.

Please send feature requests by email to [email protected] or open a GitHub issue.

tmux releases are now made approximately every six months, around the same time as OpenBSD releases (tmux is part of OpenBSD) but not necessarily on the same day.

tmux version numbers (as reported by tmux -V and display -p '#{version}') match one of the following:

• Main releases have a version with one digit after the period, such as 2.9 or 3.0. The number increases with each release, so 2.8, 2.9, 3.0, 3.1 and so on.

• Patch releases have a letter following the last digit, such as 2.9a or 3.0a. These contain a small number of changes to fix any bugs found shortly after release.

• The development source tree (master in Git) has a version prefixed by "next-", for example next-3.1 is the code that will eventually become the 3.1 release.

• Release candidates have an "-rc" suffix, optionally with a number. So the first 3.1 release candidate is 3.1-rc, the second 3.1-rc2 and so on.

• tmux in OpenBSD does not have a version number. Until OpenBSD 6.6, it did not support the -V flag; in 6.6 and later it does and reports the OpenBSD version number prefixed by "openbsd-", for example openbsd-6.6.

Aside from the patch releases and release candidates mentioned above, tmux version numbers have no special significance. tmux 3.0 is the release after tmux 2.9, nothing more.

It is already widely available. tmux and tmux-256color entries are provided by modern ncurses(3) and can be used instead by setting the default-terminal option.

This message usually means the tmux server has crashed.

If the problem can be reproduced, please open a issue reporting this - there is information in the CONTRIBUTING file on what to include and how to get logs from tmux.

It can also be useful to enable core dumps to see why tmux crashed. On most platforms this can be done by running ulimit -c unlimited before starting tmux; if it crashes again it may generate a core file in the directory where it is started. This may be called tmux.core or core.* or just core. It can be loaded into gdb like this:

$ gdb `which tmux` /path/to/core/file
...
(gdb) bt full

If this works, include the output in the issue.

Check if tmux is still running with pgrep or ps. If not, then the server probably crashed or was killed and the sessions are gone.

If tmux is still running, most likely something deleted the socket in /tmp. The tmux server can be asked to recreate its socket by sending it the USR1 signal, for example: pkill -USR1 tmux

On a few platforms, common terminal descriptions such as xterm do not include colour. screen ignores this, tmux does not. If the terminal emulator in use supports colour, use a value for TERM which correctly lists this, such as xterm-color.

Some consoles don't like attempts to set the window title. Tell tmux not to do this by turning off the set-titles option (you can do this in .tmux.conf:

set -g set-titles off

If this doesn't fix it, send a bug report.

The default key is C-b because the prototype of tmux was originally developed inside screen and C-b was chosen not to clash with the screen meta key.

To change it, change the prefix option, and - if required - move the binding of the send-prefix command from C-b (C-b C-b sends C-b by default) to the new key. For example:

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

tmux requires a system that supports UTF-8 (that is, where the C library has a UTF-8 locale) and will not start if support is missing.

tmux will attempt to detect if the terminal it is running in supports UTF-8 by looking at the LC_ALL, LC_CTYPE and LANG environment variables.

If it believes the terminal is not compatible with UTF-8, any UTF-8 characters will be replaced with underscores. The -u flag explicitly tells tmux that the terminal supports UTF-8:

$ tmux -u new

Provided the underlying terminal supports 256 colours, it is usually sufficient to add one of the following to ~/.tmux.conf:

set -g default-terminal "screen-256color"

Or:

set -g default-terminal "tmux-256color"

And make sure that TERM outside tmux also shows 256 colours, or use the tmux -2 flag.

tmux must be told that the terminal outside supports RGB colour. This is done by specifying the RGB or Tc terminfo(5) flags. RGB is the official flag, Tc is a tmux extension.

With tmux 3.2 and later this can be added with the terminal-features option:

set -as terminal-features ",gnome*:RGB"

Or for any tmux version the terminal-overrides option:

set -as terminal-overrides ",gnome*:Tc"

For tmux itself, colours may be specified in hexadecimal, for example bg=#ff0000.

Some terminals or certain fonts (particularly some Japanese fonts) do not correctly handle UTF-8 line drawing characters.

The U8 capability forces tmux to use ACS instead of UTF-8 line drawing:

set -as terminal-overrides ",*:U8=0"

Terminals do not offer fine-grained mouse support - tmux can either turn on the mouse and receive all mouse events (clicks, scrolling, everything) or it can leave the mouse off and receive no events.

So it is not possible to configure tmux such that it handles some mouse behaviours and the terminal others, it is all or nothing (mouse option on or off).

However, when an application turns on the mouse, most terminals provide a way to bypass it. On many Linux terminals this is holding down the Shift key; for iTerm2 it is the option key.

Note that tmux makes no attempt to keep the terminal scrollback consistent (it is impossible to do this with multiple windows or panes), so it is very likely to be incomplete.

Disabling a mouse behaviour in tmux rather than having the terminal handle it is done by unbinding the appropriate key bindings, for example to stop tmux changing the current window when the status line is clicked on, unbind MouseDown1Status in the root table:

unbind -Troot MouseDown1Status

Before tmux 1.9, styles (the colours and attributes of various things) were each configured with three options - one for the foreground colour (such as mode-fg), one for the background (such as mode-bg) and one for the attributes (such as mode-attr).

In tmux 1.9 each set of three options were combined into a single option (so mode-fg, mode-bg and mode-attr became mode-style) and in tmux 2.9 the old options were removed. So for example:

set -g mode-fg yellow
set -g mode-bg red
set -g mode-attr blink,underline

Should be changed to:

set -g mode-style fg=yellow,bg=red,blink,underline

The format of style options is described in the manual.

Terminal applications like tmux receive key presses as a stream of bytes with special keys marked by the ASCII ESC character (\033). The problem - and the reason for escape-time - is that as well as marking special keys, the same ASCII ESC is also used for the Escape key itself.

If tmux gets a \033 byte followed a short time later by an x, has the user pressed Escape followed by x, or have they pressed M-x? There is no guaranteed way to know.

The solution to this problem used by tmux and most other terminal applications is to introduce a delay. When tmux receives \033, it starts a timer - if the timer expires without any following bytes, then the key is Escape. The downside to this is that there is a delay before an Escape key press is recognised.

If tmux is running on the same computer as the terminal, or over a fast network, then typically the bytes representing a key will all arrive together, so an escape-time of zero is likely to be fine. Over a slower network, a larger value would be better.

tmux sends modified function keys using xterm(1)-style escape sequences. This can be verified using cat, for example pressing M-Left:

$ cat
^[[1;3D

If this is different, then TERM outside tmux is probably incorrect and tmux can't recognise the keys coming from the outside terminal.

If it is correct, then some applications inside tmux do not recognise these keys if TERM is set to screen or screen-256color, because these terminal descriptions lack the capabilities. The tmux and tmux-256color descriptions do have such capabilities, so using those instead may work. In .tmux.conf:

set -g default-terminal tmux-256color

When using the #(command) construction to include the output from a command in the status line, the command will be parsed twice. First, when it's read by the configuration file or the command-prompt parser, and second when the status line is being drawn and the command is passed to the shell. For example, to echo the string "(test)" to the status line, either single or double quotes could be used:

set -g status-right "#(echo \\\\(test\\\\))"
set -g status-right '#(echo \\\(test\\\))'

In both cases, the status-right option will be set to the string #(echo \\(test\\)) and the command executed will be echo \(test\).

Automatic window renaming may use a lot of CPU, particularly on slow computers: if this is a problem, turn it off with setw -g automatic-rename off. If this doesn't fix it, please report the problem.

It isn't possible to get the load average portably in code and it is preferable not to add portability goop. The following works on at least Linux, *BSD and OS X:

uptime|awk '{split(substr($0, index($0, "load")), a, ":"); print a[2]}'

One or more of the windows can be linked into multiple sessions manually with link-window, or a grouped session with all the windows can be created with new-session -t.

GNU screen does not support italics and the screen terminal description uses the italics escape sequence incorrectly.

As of tmux 2.1, if default-terminal is set to screen or matches screen-*, tmux will behave like screen and italics will be disabled.

To enable italics, make sure you are using the tmux terminal description:

set -g default-terminal "tmux"

Show the default session options by starting a new tmux server with no configuration file:

$ tmux -Lfoo -f/dev/null start\; show -g

Or the default window options:

$ tmux -Lfoo -f/dev/null start\; show -gw

See this page.

Until version 2.9, tmux limits the size of the window to the smallest attached client. If it didn't do this then it would be impossible to see the entire window. The dots mark the size of the window tmux can display.

To avoid this, detach all other clients when attaching:

$ tmux attach -d

Or from inside tmux by detaching individual clients with C-b D or all using:

C-b : attach -d

With 2.9 or later, setting the window-size option to largest will use the largest attached client rather than smallest.

ssh-agent(1) sets an environment variable (SSH_AUTH_SOCK) which needs to be present in every shell process.

It is possible to make sure SSH_AUTH_SOCK is set before running tmux, then it will be in the global environment and will be set for every pane created in tmux. The update-environment option contains SSH_AUTH_SOCK by default so it will update SSH_AUTH_SOCK in the session environment when a session is attached or a new session is created. However, if SSH_AUTH_SOCK is not set when a session attached, update-environment will cause SSH_AUTH_SOCK to be removed from the environment and not set for new panes. See here and here.

In practice, it is more reliable to set up ssh-agent(1) in a shell profile that is run for every shell regardless of tmux. For a Bourne-style shell like ksh(1) or bash(1), something like this in .profile, .kshrc, .bash_profile or .bashrc:

[ ! -f ~/.ssh.agent ] && ssh-agent -s >~/.ssh.agent
eval `cat ~/.ssh.agent` >/dev/null
if ! kill -0 $SSH_AGENT_PID 2>/dev/null; then
        ssh-agent -s >~/.ssh.agent
        eval `cat ~/.ssh.agent` >/dev/null
fi

tmux takes care not to send escape sequences to a terminal that it isn't going to understand because it can't predict how it will react.

However, it can be forced to pass an escape sequence through by wrapping it in a special form of the DCS sequence with the content prefixed by tmux;. Any \033 characters in the wrapped sequence must be doubled, for example:

\033Ptmux;\033\033]1337;SetProfile=NewProfileName\007\033\\

Will pass this iTerm2 special escape sequence \033]1337;SetProfile=NewProfileName\007 through to the terminal without tmux discarding it.

This feature should be used with care. Note that because tmux isn't aware of any changes made to the terminal state by the passthrough escape sequence, it is possible for it to undo them.

The passthrough escape sequence is no longer necessary for changing the cursor colour or style as tmux now has its own support (see the Cs, Cr, Ss and Se capabilities).

As of tmux 3.3, the allow-passthrough option must be set to on or all for the passthrough sequence to work.

For set-option, the -q flag suppresses warnings about unknown options, for example:

set -gq mode-bg red

Since tmux 2.3, the running server version is available in the version format variable. This can be used with if-shell, if-shell -F (since tmux 2.0) or %if (since tmux 2.4) to check for specific server versions.

The m (since tmux 2.6) and m/r (since tmux 3.0) modifiers are most useful for this. For example to show a green status line if running a development build, blue if version 3.1 or above and red otherwise:

%if #{m/r:^next-,#{version}}
set -g status-style bg=green
%elif #{&&:#{m/r:^[0-9] \.[0-9] $,#{version}},#{e|>=|f:#{version},3.1}}
set -g status-style bg=blue
%else
set -g status-style bg=red
%endif

For versions older than tmux 2.3, if-shell and tmux -V must be used.

Note that on OpenBSD version numbers the tmux version number tracks the OpenBSD version, see this FAQ entry for information on tmux version numbers.

tmux is not a file transfer program and these protocols are more effort to support than their remaining popularity deserves. Detach tmux before attempting to use them.