Annotation of embedaddon/tmux/FAQ, revision 1.1
1.1 ! misho 1: tmux frequently asked questions
! 2:
! 3: ******************************************************************************
! 4: * PLEASE NOTE: most display problems are due to incorrect TERM! Before *
! 5: * reporting problems make SURE that TERM settings are correct inside and *
! 6: * outside tmux. *
! 7: * *
! 8: * Inside tmux TERM must be "screen" or similar (such as "screen-256color"). *
! 9: * Don't bother reporting problems where it isn't! *
! 10: * *
! 11: * Outside, it must match your terminal: particularly, use "rxvt" for rxvt *
! 12: * and derivatives. *
! 13: ******************************************************************************
! 14:
! 15: * How is tmux different from GNU screen?
! 16:
! 17: tmux and GNU screen have many similarities. Some of the main differences I am
! 18: aware of are (bearing in mind I haven't used screen for a few years now):
! 19:
! 20: - tmux uses a client-server model. Each server has single Unix domain socket in
! 21: /tmp and within one server there are multiple sessions which may be attached
! 22: to multiple clients (terminals).
! 23:
! 24: This has advantages, notably: windows may be linked simultaneously to
! 25: multiple sessions; windows may be moved freely between sessions; and a client
! 26: may be switched between sessions easily (C-b D). There is one major
! 27: disadvantage: if the server crashes, game over, all sessions die. In
! 28: practice, however, tmux is quite stable and gets more so as people report any
! 29: bugs they hit :-).
! 30:
! 31: This model is different from screen, where typically each new screen instance
! 32: is independent. tmux supports the same behaviour by using multiple servers
! 33: with the -L option but it is not typically recommended.
! 34:
! 35: - Different command interfaces. One of the goals of tmux is that the shell
! 36: should be easily usable as a scripting language - almost all tmux commands
! 37: can be used from the shell and behave identically whether used from the
! 38: shell, from a key binding or from the command prompt. Personally I also find
! 39: tmux's command interface much more consistent and clearer, but this is
! 40: subjective.
! 41:
! 42: - tmux calls window names (what you see in the status line) "names", screen
! 43: calls them "titles".
! 44:
! 45: - tmux has a multiple paste buffers. Not a major one but comes in handy quite a
! 46: lot.
! 47:
! 48: - tmux supports automatically renaming windows to the running application
! 49: without gross hacks using escape sequences. Its even on by default.
! 50:
! 51: - tmux has a choice of vi or emacs key layouts. Again, not major, but I use
! 52: emacs so if tmux did support only one key set it would be emacs and then all
! 53: the vi users would get humpy. Key bindings may be completely reconfigured in
! 54: any case.
! 55:
! 56: - tmux has an option to limit the window size.
! 57:
! 58: - tmux has search in windows (C-b f).
! 59:
! 60: - The window split (pane) model is different. tmux has two objects, windows and
! 61: panes; screen has just windows. This difference has several implications:
! 62:
! 63: * In screen you can have a window appear in several layouts, in tmux a pane
! 64: can only be in one window (fixing this is a big todo item but quite
! 65: invasive).
! 66:
! 67: * tmux layouts are immutable and do not get changed unless you modify them.
! 68:
! 69: * In tmux, all panes are closed when you kill a window.
! 70:
! 71: * tmux panes do not have individual names, titles and so on.
! 72:
! 73: I think tmux's model is much easier to manage and navigate within a window,
! 74: but breaking panes off from and joining them to windows is more clumsy.
! 75:
! 76: tmux also has support for preset pane layouts.
! 77:
! 78: - tmux's status line syntax is more readable and easier to use. I think it'd be
! 79: hard for anyone to argue with this. tmux doesn't support running a command
! 80: constantly and always using the last line of its output, commands must be run
! 81: again each time.
! 82:
! 83: - tmux has modern, easily extended code. Again hard to argue screen is better
! 84: if you have looked at the code.
! 85:
! 86: - tmux depends on libevent. I don't see this as a disadvantage: libevent is
! 87: small and portable, and on modern systems with current package management
! 88: systems dependencies are not an issue. libevent brings advantages in code
! 89: simplicity and performance.
! 90:
! 91: - screen allows the window to be bigger than the terminal and can pan around
! 92: it. tmux limits the size to the largest attached client. This is a big todo
! 93: item for tmux but it is not trivial.
! 94:
! 95: - screen has builtin serial and telnet support; this is bloat and is unlikely
! 96: to be added to tmux.
! 97:
! 98: - Environment handling is different.
! 99:
! 100: - tmux tends to be more demanding on the terminal so tends to show up terminal
! 101: and application bugs which screen does not.
! 102:
! 103: - screen has wider platform support, for example IRIX, and for odd terminals.
! 104:
! 105: * I found a bug! What do I do?
! 106:
! 107: Check the latest version of tmux from Git to see if the problem is still
! 108: reproducible. Sometimes the length of time between releases means a lot of
! 109: fixes can be sitting in Git and the problem might already be fixed.
! 110:
! 111: Please send bug reports by email to nicholas.marriott@gmail.com or
! 112: tmux-users@googlegroups.com. Please include as much of the following
! 113: information as possible:
! 114:
! 115: - the version of tmux you are running;
! 116: - the operating system you are using and its version;
! 117: - the terminal emulator you are using and the TERM setting when tmux was
! 118: started;
! 119: - a description of the problem;
! 120: - if the problem is repeatable, the steps to repeat the problem;
! 121: - for screen corruption issues, a screenshot and the output of "infocmp $TERM"
! 122: from outside tmux are often very useful.
! 123:
! 124: * Why doesn't tmux do $x?
! 125:
! 126: Please send feature requests by email to tmux-users@googlegroups.com.
! 127:
! 128: * Why do you use the screen terminal description inside tmux? It sucks.
! 129:
! 130: It is already widely available. It is planned to change to something else such
! 131: as xterm-xfree86 at some point, if possible.
! 132:
! 133: * I don't see any colour in my terminal! Help!
! 134:
! 135: On some platforms, common terminal descriptions such as xterm do not include
! 136: colour. screen ignores this, tmux does not. If the terminal emulator in use
! 137: supports colour, use a value for TERM which correctly lists this, such as
! 138: xterm-color.
! 139:
! 140: * tmux freezes my terminal when I attach to a session. I even have to kill -9
! 141: the shell it was started from to recover!
! 142:
! 143: Some consoles really really don't like attempts to set the window title. Tell
! 144: tmux not to do this by turning off the "set-titles" option (you can do this
! 145: in .tmux.conf):
! 146:
! 147: set -g set-titles off
! 148:
! 149: If this doesn't fix it, send a bug report.
! 150:
! 151: * Why is C-b the prefix key? How do I change it?
! 152:
! 153: The default key is C-b because the prototype of tmux was originally developed
! 154: inside screen and C-b was chosen not to clash with the screen meta key. It
! 155: also has the advantage of not interfering with the use of C-a for start-of-line
! 156: in emacs and the shell (although it does interfere with previous-character).
! 157:
! 158: Changing is simple: change the "prefix-key" option, and - if required - move
! 159: the binding of the "send-prefix" command from C-b (C-b C-b sends C-b by
! 160: default) to the new key. For example:
! 161:
! 162: set -g prefix C-a
! 163: unbind C-b
! 164: bind C-a send-prefix
! 165:
! 166: * How do I use UTF-8?
! 167:
! 168: When running tmux in a UTF-8 capable terminal, UTF-8 must be turned on in tmux;
! 169: as of release 0.9, tmux attempts to autodetect a UTF-8-capable terminal by
! 170: checking the LC_ALL, LC_CTYPE and LANG environment variables. list-clients may
! 171: be used to check if this is detected correctly; if not, the -u command-line
! 172: flag may be specified when creating or attaching a client to a tmux session:
! 173:
! 174: $ tmux -u new
! 175:
! 176: Since the 1.0 release, tmux will turn on UTF-8 related options automatically
! 177: (ie status-utf8, and utf8) if the above conditions are met.
! 178:
! 179: * How do I use a 256 colour terminal?
! 180:
! 181: Provided the underlying terminal supports 256 colours, it is usually sufficient
! 182: to add the following to ~/.tmux.conf:
! 183:
! 184: set -g default-terminal "screen-256color"
! 185:
! 186: Note that some platforms do not support "screen-256color" ("infocmp
! 187: screen-256color" will return an error) - in this case see the next entry in
! 188: this FAQ.
! 189:
! 190: tmux attempts to detect a 256 colour terminal both by looking at the colors
! 191: terminfo entry and by looking for the string "256col" in the TERM environment
! 192: variable.
! 193:
! 194: If both these methods fail, the -2 flag may be passed to tmux when attaching
! 195: to a session to indicate the terminal supports 256 colours.
! 196:
! 197: * vim or $otherprogram doesn't display 256 colours. What's up?
! 198:
! 199: Some programs attempt to detect the number of colours a terminal is capable of
! 200: by checking the colors terminfo or Co termcap entry. However, this is not
! 201: reliable, and in any case is missing from the "screen" terminal description
! 202: used inside tmux.
! 203:
! 204: There are two options (aside from using "screen-256color") to allow programs to
! 205: recognise they are running on a 256-colour terminal inside tmux:
! 206:
! 207: - Manually force the application to use 256 colours always or if TERM is set to
! 208: screen. For vim, you can do this by overriding the t_Co option, see
! 209: http://vim.wikia.com/wiki/256_colors_in_vim.
! 210: - Creating a custom terminfo file that includes colors#256 in ~/.terminfo and
! 211: using it instead. These may be compiled with tic(1).
! 212:
! 213: * How do I make Ctrl-PgUp and Ctrl-PgDn work in vim?
! 214:
! 215: tmux supports passing through ctrl (and where supported by the client terminal,
! 216: alt and shift) modifiers to function keys using xterm(1)-style key sequences.
! 217: This may be enabled per window, or globally with the tmux command:
! 218:
! 219: setw -g xterm-keys on
! 220:
! 221: Because the TERM variable inside tmux must be set to "screen", vim will not
! 222: automatically detect these keys are available; however, the appropriate key
! 223: sequences can be overridden in .vimrc using the following:
! 224:
! 225: if &term == "screen"
! 226: set t_kN=^[[6;*~
! 227: set t_kP=^[[5;*~
! 228: endif
! 229:
! 230: And similarly for any other keys for which modifiers are desired.
! 231:
! 232: Please note that the "xterm-keys" setting may affect other programs, in the
! 233: same way as running them in a standard xterm; for example most shells do not
! 234: expect to receive xterm(1)-style key sequences so this setting may prevent keys
! 235: such as ctrl-left and ctrl-right working correctly. tmux also passes through
! 236: the ctrl (bit 5 set, for example ^[[5~ to ^[[5^) modifier in non-xterm(1) mode;
! 237: it may be possible to configure vim to accept these, an example of how to do so
! 238: would be welcome.
! 239:
! 240: vim users may also want to set the "ttyfast" option inside tmux.
! 241:
! 242: * How do I make ctrl and shift arrow keys work in emacs?
! 243:
! 244: The terminal-init-screen function in term/screen.el is called for new frames,
! 245: but it doesn't configure any function keys.
! 246:
! 247: If the tmux xterm-keys option is on, it is enough to define the same keys as
! 248: xterm. Add the following to init.el or .emacs to do this:
! 249:
! 250: (defadvice terminal-init-screen
! 251: ;; The advice is named `tmux', and is run before `terminal-init-screen' runs.
! 252: (before tmux activate)
! 253: ;; Docstring. This describes the advice and is made available inside emacs;
! 254: ;; for example when doing C-h f terminal-init-screen RET
! 255: "Apply xterm keymap, allowing use of keys passed through tmux."
! 256: ;; This is the elisp code that is run before `terminal-init-screen'.
! 257: (if (getenv "TMUX")
! 258: (let ((map (copy-keymap xterm-function-map)))
! 259: (set-keymap-parent map (keymap-parent input-decode-map))
! 260: (set-keymap-parent input-decode-map map))))
! 261:
! 262: And ensure .tmux.conf contains "set -g xterm-keys on".
! 263:
! 264: Alternatively, the screen.el file can be copied to the load path and
! 265: customized.
! 266:
! 267: * Why doesn't elinks set the window title inside tmux?
! 268:
! 269: There isn't a way to detect if a terminal supports setting the window title, so
! 270: elinks attempts to guess by looking at the environment. Rather than looking for
! 271: TERM=screen, it uses the STY variable to detect if it is running in screen;
! 272: tmux does not use this so the check fails. A workaround is to set STY before
! 273: running elinks.
! 274:
! 275: The following shell function does this, and also clears the window title on
! 276: exit (elinks, for some strange reason, sets it to the value of TERM):
! 277:
! 278: elinks() {
! 279: STY= `which elinks` $*
! 280: echo -ne \\033]0\;\\007;
! 281: }
! 282:
! 283: * What is the proper way to escape characters with #(command)?
! 284:
! 285: When using the #(command) construction to include the output from a command in
! 286: the status line, the command will be parsed twice. First, when it's read by the
! 287: configuration file or the command-prompt parser, and second when the status
! 288: line is being drawn and the command is passed to the shell. For example, to
! 289: echo the string "(test)" to the status line, either single or double quotes
! 290: could be used:
! 291:
! 292: set -g status-right "#(echo \\\\(test\\\\))"
! 293: set -g status-right '#(echo \\\(test\\\))'
! 294:
! 295: In both cases, the status-right option will be set to the string "#(echo
! 296: \\(test\\))" and the command executed will be "echo \(test\)".
! 297:
! 298: * tmux uses too much CPU. What do I do?
! 299:
! 300: Automatic window renaming may use a lot of CPU, particularly on slow computers:
! 301: if this is a problem, turn it off with "setw -g automatic-rename off". If this
! 302: doesn't fix it, please report the problem.
! 303:
! 304: * I use PuTTY and my tmux window pane separators are all qqqqqqqqq's!
! 305:
! 306: PuTTY is using a character set translation that doesn't support ACS line
! 307: drawing. With a Unicode font, try setting PuTTY to use a different translation
! 308: on the Window -> Translation configuration page. For example, change UTF-8 to
! 309: ISO-8859-1 or CP437. It may also be necessary to adjust the way PuTTY treats
! 310: line drawing characters in the lower part of the same configuration page.
! 311:
! 312: * What is the best way to display the load average? Why no #L?
! 313:
! 314: It isn't possible to get the load average portably in code and it is preferable
! 315: not to add portability goop. The following works on at least Linux, *BSD and OS
! 316: X:
! 317:
! 318: uptime|awk '{split(substr($0, index($0, "load")), a, ":"); print a[2]}'
! 319:
! 320: * How do I attach the same session to multiple clients but with a different
! 321: current window, like screen -x?
! 322:
! 323: One or more of the windows can be linked into multiple sessions manually with
! 324: link-window, or a grouped session with all the windows can be created with
! 325: new-session -t.
! 326:
! 327: * Ctrl and arrow keys doesn't work in putty! What do I do?
! 328:
! 329: putty inverts the sense of the cursor key mode on ctrl, which is a bit hard for
! 330: tmux to detect properly. To get ctrl keys right, change the terminfo settings
! 331: so kUP5 (Ctrl-Up etc) are the adjusted versions, and disable smkx/rmkx so tmux
! 332: doesn't change the mode. For example with this line in .tmux.conf (assuming you
! 333: have TERM set to xterm):
! 334:
! 335: set -g terminal-overrides "xterm*:kLFT5=\eOD:kRIT5=\eOC:kUP5=\eOA:kDN5=\eOB:smkx@:rmkx@"
! 336:
! 337: Note that this will only work in tmux 1.2 and above.
! 338:
! 339: * How can I blank the tmux window?
! 340:
! 341: GNU screen has a feature whereby it will blank the screen after a period of
! 342: inactivity. To do the same thing in tmux, use the lock-command setting, for
! 343: example (with GNU bash):
! 344:
! 345: set -g lock-command 'tput civis && read -s -n1'
! 346:
! 347: This will remove the cursor and tell the shell to quit once a key has been
! 348: pressed. For zsh, use "read -s -k1".
! 349:
! 350: In addition, it's possible to have both blanking and locking (for instance via
! 351: lock(1) or vlock(1)) by using the following:
! 352:
! 353: bind x set lock-command '/usr/bin/vlock' \; lock-client \; set lock-command 'tput civis && read -s -n1'
! 354:
! 355: * I don't see italics! Or less and vim show italics and reverse the wrong way round!
! 356:
! 357: GNU screen does not support italics and the "screen" terminfo description uses
! 358: the italics escape sequence incorrectly.
! 359:
! 360: As of tmux 2.1, if default-terminal is set to "screen" or matches "screen-*",
! 361: tmux will behave like screen and italics will be disabled.
! 362:
! 363: To enable italics, create a new terminfo entry called "tmux" (some platforms
! 364: may already have this, you can check with "infocmp tmux"):
! 365:
! 366: $ cat <<EOF|tic -x -
! 367: tmux|tmux terminal multiplexer,
! 368: ritm=\E[23m, rmso=\E[27m, sitm=\E[3m, smso=\E[7m, Ms@,
! 369: use=xterm+tmux, use=screen,
! 370:
! 371: tmux-256color|tmux with 256 colors,
! 372: use=xterm+256setaf, use=tmux,
! 373: EOF
! 374: $
! 375:
! 376: And tell tmux to use it in ~/.tmux.conf:
! 377:
! 378: set -g default-terminal "tmux"
! 379:
! 380: If using urxvt, make sure you have an italics capable font enabled. for
! 381: example, add to ~/.Xdefaults:
! 382:
! 383: urxvt.italicFont: xft:Bitstream Vera Sans Mono:italic:autohint=true
! 384:
! 385: * How can I make tmux use my terminal's scrollback buffer?
! 386:
! 387: Normally, tmux enables the terminal's "alternate screen". Most terminals (such
! 388: as xterm) do not save scrollback for the alternate screen. You might prefer
! 389: tmux to use the normal screen, so it uses your terminal's scrollback
! 390: buffer. This way, you can access the scrollback buffer as usual, for example
! 391: using the mouse wheel - although there is no guarantee output inside tmux will
! 392: always (or ever) be added to the scrollback.
! 393:
! 394: You can make tmux use the normal screen by telling it that your terminal does
! 395: not have an alternate screen. Put the following in ~/.tmux.conf:
! 396:
! 397: set -ga terminal-overrides ',xterm*:smcup@:rmcup@'
! 398:
! 399: Adjust if your $TERM does not start with xterm.
! 400:
! 401: tmux will still emulate the alternate screen for applications run under tmux,
! 402: so you don't really lose anything with this setting. The only disadvantage is
! 403: that when you exit tmux, it will not restore whatever was there before you
! 404: started.
! 405:
! 406: * How do I see the default configuration?
! 407:
! 408: Show the default session options by starting a new tmux server with no
! 409: configuration file:
! 410:
! 411: $ tmux -Lfoo -f/dev/null start\; show -g
! 412:
! 413: Or the default window options:
! 414:
! 415: $ tmux -Lfoo -f/dev/null start\; show -gw
! 416:
! 417: * How do I copy a selection from tmux to the system's clipboard?
! 418:
! 419: When running in xterm(1), tmux can automatically send copied text to the
! 420: clipboard. This is controlled by the set-clipboard option and also needs this
! 421: X resource to be set:
! 422:
! 423: XTerm*disallowedWindowOps: 20,21,SetXprop
! 424:
! 425: For rxvt-unicode (urxvt), there is an unofficial Perl extension here:
! 426:
! 427: http://anti.teamidiot.de/static/nei/*/Code/urxvt/
! 428:
! 429: Otherwise a key binding for copy mode using xclip (or xsel) works:
! 430:
! 431: bind -temacs-copy C-y copy-pipe "xclip -i >/dev/null"
! 432:
! 433: Or for inside and outside copy mode with the prefix key:
! 434:
! 435: bind C-y run -b "tmux save-buffer - | xclip -i"
! 436:
! 437: On OS X, look at the pbcopy(1) and pbpaste(1) commands.
! 438:
! 439: * Why don't some commands work inside tmux on OS X?
! 440:
! 441: Apple requires some undocumented, unsupported fiddling to allow commands that
! 442: interact with the GUI to work. Neither tmux itself nor most shells do this, so
! 443: an external program is required. This can be found here:
! 444:
! 445: https://github.com/ChrisJohnsen/tmux-MacOSX-pasteboard
! 446:
! 447: Affected commands may include say(1), pbcopy(1), pbpaste(1) and ssh(1).
! 448:
! 449: * Why do I see dots around a session when I attach to it?
! 450:
! 451: tmux limits the size of the window to the smallest attached session. If
! 452: it didn't do this then it would be impossible to see the entire window.
! 453: The dots mark the size of the window tmux can display.
! 454:
! 455: To avoid this, detach all other clients when attaching:
! 456:
! 457: $ tmux attach -d
! 458:
! 459: Or from inside tmux by detaching individual clients with C-b D or all
! 460: using:
! 461:
! 462: C-b : attach -d
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to FAQ CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / tmux