PLEASE NOTE: most display problems are due to incorrect TERM! Beforereporting problems make SURE that TERM settings are correct inside andoutside 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 rxvtand derivatives.

The environment variableTERM tells applications the name of a terminaldescription to read from theterminfo(5) database. Each description consistsof a number of named capabilities which tell applications what to send tocontrol the terminal. For example, thecup capability contains the escapesequence used to move the cursor up.

It is important thatTERM points to the correct description for the terminal anapplication is running in - if it doesn't, applications may misbehave.

Theinfocmp(1) command shows the contents of a terminal description and thetic(1) command builds and installs a description from a file (the-x flagis normally required with both).

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

Please send bug reports by email tonicholas.marriott@gmail.com ortmux-users@googlegroups.com or by opening a GitHub issue. Please see theCONTRIBUTINGfile for information on what to include.

Please send feature requests by email totmux-users@googlegroups.com or open a GitHub issue.

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

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

• Main releases have a version with one digit after the period, such as 2.9 or3.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 afterrelease.

• 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.1release.

• Release candidates have an "-rc" suffix, optionally with a number. So thefirst 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 notsupport the-V flag; in 6.6 and later it does and reports the OpenBSDversion number prefixed by "openbsd-", for example openbsd-6.6.

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

It is already widely available.tmux andtmux-256color entries are providedby modernncurses(3) and can be used instead by setting thedefault-terminaloption.

This message usually means the tmux server has crashed.

If the problem can be reproduced, please open a issue reporting this - there isinformation in theCONTRIBUTINGfile 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 mostplatforms this can be done by runningulimit -c unlimited before startingtmux; if it crashes again it may generate a core file in the directory where itis started. This may be calledtmux.core orcore.* or justcore. It canbe loaded intogdb 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 withpgrep orps. If not, then the serverprobably 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 theUSR1signal, for example:pkill -USR1 tmux

On a few platforms, common terminal descriptions such asxterm do not includecolour. screen ignores this, tmux does not. If the terminal emulator in usesupports colour, use a value forTERM which correctly lists this, such asxterm-color.

Some consoles don't like attempts to set the window title. Tell tmux not to dothis by turning off theset-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 developedinside screen and C-b was chosen not to clash with the screen meta key.

To change it, change theprefix option, and - if required - move the bindingof thesend-prefix command from C-b (C-b C-b sends C-b by default) to the newkey. For example:

set -g prefix C-aunbind C-bbind C-a send-prefix

tmux requires a system that supports UTF-8 (that is, where the C library has aUTF-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 bylooking at theLC_ALL,LC_CTYPE andLANG environment variables.

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

$ tmux -u new

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

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

Or:

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

And make sure thatTERM 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 doneby specifying theRGB orTcterminfo(5) flags.RGB is the officialflag,Tc is a tmux extension.

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

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

Or for any tmux version theterminal-overrides option:

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

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

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

TheU8 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 themouse and receive all mouse events (clicks, scrolling, everything) or it canleave the mouse off and receive no events.

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

However, when an application turns on the mouse, most terminals provide a wayto bypass it. On many Linux terminals this is holding down theShift key; foriTerm2 it is theoption key.

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

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

unbind -Troot MouseDown1Status

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

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

set -g mode-fg yellowset -g mode-bg redset -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 describedin the manual.

Terminal applications like tmux receive key presses as a stream of bytes withspecial keys marked by the ASCII ESC character (\033). The problem - and thereason for escape-time - is that as well as marking special keys, the sameASCII 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 userpressed Escape followed by x, or have they pressed M-x? There is no guaranteedway to know.

The solution to this problem used by tmux and most other terminal applicationsis to introduce a delay. When tmux receives\033, it starts a timer - if thetimer expires without any following bytes, then the key is Escape. The downsideto 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 fastnetwork, then typically the bytes representing a key will all arrive together,so anescape-time of zero is likely to be fine. Over a slower network, a largervalue would be better.

tmux sends modified function keys usingxterm(1)-style escape sequences. Thiscan be verified usingcat, for example pressing M-Left:

$ cat^[[1;3D

If this is different, thenTERM outside tmux is probably incorrect and tmuxcan't recognise the keys coming from the outside terminal.

If it is correct, then some applications inside tmux do not recognise thesekeys ifTERM is set toscreen orscreen-256color, because these terminaldescriptions lack the capabilities. Thetmux andtmux-256color descriptionsdo 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 commandin the status line, the command will be parsed twice. First, when it's read bythe configuration file or the command-prompt parser, and second when the statusline is being drawn and the command is passed to the shell. For example, toecho the string "(test)" to the status line, either single or double quotescould 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 beecho \(test\).

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

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

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 withlink-window, or a grouped session with all the windows can be created withnew-session -t.

GNU screen does not support italics and thescreen terminal description usesthe italics escape sequence incorrectly.

As of tmux 2.1, ifdefault-terminal is set toscreen or matchesscreen-*,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 noconfiguration file:

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

Or the default window options:

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

Seethis page.

Until version 2.9, tmux limits the size of the window to the smallest attachedclient. If it didn't do this then it would be impossible to see the entirewindow. 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 allusing:

C-b : attach -d

With 2.9 or later, setting thewindow-size option tolargest will use thelargest attached client rather than smallest.

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

It is possible to make sureSSH_AUTH_SOCK is set before running tmux, then itwill be in the global environment and will be set for every pane created intmux. Theupdate-environment option containsSSH_AUTH_SOCK by default so itwill updateSSH_AUTH_SOCK in the session environment when a session isattached or a new session is created. However, ifSSH_AUTH_SOCK isnot setwhen a session attached,update-environment will causeSSH_AUTH_SOCK to beremoved from the environment and not set for new panes. Seehereandhere.

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

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

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

However, it can be forced to pass an escape sequence through by wrapping it ina special form of the DCS sequence with the content prefixed bytmux;. 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 tmuxdiscarding it.

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

The passthrough escape sequence is no longer necessary for changing the cursorcolour or style as tmux now has its own support (see theCs,Cr,Ss andSe capabilities).

As of tmux 3.3, theallow-passthrough option must be set toon orall forthe passthrough sequence to work.

Forset-option, the-q flag suppresses warnings about unknown options, forexample:

set -gq mode-bg red

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

Them (since tmux 2.6) andm/r (since tmux 3.0) modifiers are most usefulfor this. For example to show a green status line if running a developmentbuild, 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%elseset -g status-style bg=red%endif

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

Note that on OpenBSD version numbers the tmux version number tracks the OpenBSDversion, seethis FAQentryfor information on tmux version numbers.

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