1tmux 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 17tmux and GNU screen have many similarities. Some of the main differences I am 18aware 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 107Check the latest version of tmux from Git to see if the problem is still 108reproducible. Sometimes the length of time between releases means a lot of 109fixes can be sitting in Git and the problem might already be fixed. 110 111Please send bug reports by email to nicholas.marriott@gmail.com or 112tmux-users@googlegroups.com. Please include as much of the following 113information 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 126Please 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 130It is already widely available. It is planned to change to something else such 131as xterm-xfree86 at some point, if possible. 132 133* I don't see any colour in my terminal! Help! 134 135On some platforms, common terminal descriptions such as xterm do not include 136colour. screen ignores this, tmux does not. If the terminal emulator in use 137supports colour, use a value for TERM which correctly lists this, such as 138xterm-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 143Some consoles really really don't like attempts to set the window title. Tell 144tmux not to do this by turning off the "set-titles" option (you can do this 145in .tmux.conf): 146 147 set -g set-titles off 148 149If this doesn't fix it, send a bug report. 150 151* Why is C-b the prefix key? How do I change it? 152 153The default key is C-b because the prototype of tmux was originally developed 154inside screen and C-b was chosen not to clash with the screen meta key. It 155also has the advantage of not interfering with the use of C-a for start-of-line 156in emacs and the shell (although it does interfere with previous-character). 157 158Changing is simple: change the "prefix-key" option, and - if required - move 159the binding of the "send-prefix" command from C-b (C-b C-b sends C-b by 160default) 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 168When running tmux in a UTF-8 capable terminal, UTF-8 must be turned on in tmux; 169as of release 0.9, tmux attempts to autodetect a UTF-8-capable terminal by 170checking the LC_ALL, LC_CTYPE and LANG environment variables. list-clients may 171be used to check if this is detected correctly; if not, the -u command-line 172flag may be specified when creating or attaching a client to a tmux session: 173 174 $ tmux -u new 175 176Since 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 181Provided the underlying terminal supports 256 colours, it is usually sufficient 182to add the following to ~/.tmux.conf: 183 184 set -g default-terminal "screen-256color" 185 186Note that some platforms do not support "screen-256color" ("infocmp 187screen-256color" will return an error) - in this case see the next entry in 188this FAQ. 189 190tmux attempts to detect a 256 colour terminal both by looking at the colors 191terminfo entry and by looking for the string "256col" in the TERM environment 192variable. 193 194If both these methods fail, the -2 flag may be passed to tmux when attaching 195to a session to indicate the terminal supports 256 colours. 196 197* vim or $otherprogram doesn't display 256 colours. What's up? 198 199Some programs attempt to detect the number of colours a terminal is capable of 200by checking the colors terminfo or Co termcap entry. However, this is not 201reliable, and in any case is missing from the "screen" terminal description 202used inside tmux. 203 204There are two options (aside from using "screen-256color") to allow programs to 205recognise 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 215tmux supports passing through ctrl (and where supported by the client terminal, 216alt and shift) modifiers to function keys using xterm(1)-style key sequences. 217This may be enabled per window, or globally with the tmux command: 218 219 setw -g xterm-keys on 220 221Because the TERM variable inside tmux must be set to "screen", vim will not 222automatically detect these keys are available; however, the appropriate key 223sequences 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 230And similarly for any other keys for which modifiers are desired. 231 232Please note that the "xterm-keys" setting may affect other programs, in the 233same way as running them in a standard xterm; for example most shells do not 234expect to receive xterm(1)-style key sequences so this setting may prevent keys 235such as ctrl-left and ctrl-right working correctly. tmux also passes through 236the ctrl (bit 5 set, for example ^[[5~ to ^[[5^) modifier in non-xterm(1) mode; 237it may be possible to configure vim to accept these, an example of how to do so 238would be welcome. 239 240vim 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 244The terminal-init-screen function in term/screen.el is called for new frames, 245but it doesn't configure any function keys. 246 247If the tmux xterm-keys option is on, it is enough to define the same keys as 248xterm. 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 262And ensure .tmux.conf contains "set -g xterm-keys on". 263 264Alternatively, the screen.el file can be copied to the load path and 265customized. 266 267* Why doesn't elinks set the window title inside tmux? 268 269There isn't a way to detect if a terminal supports setting the window title, so 270elinks attempts to guess by looking at the environment. Rather than looking for 271TERM=screen, it uses the STY variable to detect if it is running in screen; 272tmux does not use this so the check fails. A workaround is to set STY before 273running elinks. 274 275The following shell function does this, and also clears the window title on 276exit (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 285When using the #(command) construction to include the output from a command in 286the status line, the command will be parsed twice. First, when it's read by the 287configuration file or the command-prompt parser, and second when the status 288line is being drawn and the command is passed to the shell. For example, to 289echo the string "(test)" to the status line, either single or double quotes 290could be used: 291 292 set -g status-right "#(echo \\\\(test\\\\))" 293 set -g status-right '#(echo \\\(test\\\))' 294 295In 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 300Automatic window renaming may use a lot of CPU, particularly on slow computers: 301if this is a problem, turn it off with "setw -g automatic-rename off". If this 302doesn't fix it, please report the problem. 303 304* I use PuTTY and my tmux window pane separators are all qqqqqqqqq's! 305 306PuTTY is using a character set translation that doesn't support ACS line 307drawing. With a Unicode font, try setting PuTTY to use a different translation 308on the Window -> Translation configuration page. For example, change UTF-8 to 309ISO-8859-1 or CP437. It may also be necessary to adjust the way PuTTY treats 310line 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 314It isn't possible to get the load average portably in code and it is preferable 315not to add portability goop. The following works on at least Linux, *BSD and OS 316X: 317 318uptime|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 323One or more of the windows can be linked into multiple sessions manually with 324link-window, or a grouped session with all the windows can be created with 325new-session -t. 326 327* Ctrl and arrow keys doesn't work in putty! What do I do? 328 329putty inverts the sense of the cursor key mode on ctrl, which is a bit hard for 330tmux to detect properly. To get ctrl keys right, change the terminfo settings 331so kUP5 (Ctrl-Up etc) are the adjusted versions, and disable smkx/rmkx so tmux 332doesn't change the mode. For example with this line in .tmux.conf (assuming you 333have TERM set to xterm): 334 335set -g terminal-overrides "xterm*:kLFT5=\eOD:kRIT5=\eOC:kUP5=\eOA:kDN5=\eOB:smkx@:rmkx@" 336 337Note that this will only work in tmux 1.2 and above. 338 339* How can I blank the tmux window? 340 341GNU screen has a feature whereby it will blank the screen after a period of 342inactivity. To do the same thing in tmux, use the lock-command setting, for 343example (with GNU bash): 344 345set -g lock-command 'tput civis && read -s -n1' 346 347This will remove the cursor and tell the shell to quit once a key has been 348pressed. For zsh, use "read -s -k1". 349 350In addition, it's possible to have both blanking and locking (for instance via 351lock(1) or vlock(1)) by using the following: 352 353bind 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 357GNU screen does not support italics and the "screen" terminfo description uses 358the italics escape sequence incorrectly. 359 360As of tmux 2.1, if default-terminal is set to "screen" or matches "screen-*", 361tmux will behave like screen and italics will be disabled. 362 363To enable italics, create a new terminfo entry called "tmux" (some platforms 364may 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 376And tell tmux to use it in ~/.tmux.conf: 377 378 set -g default-terminal "tmux" 379 380If using urxvt, make sure you have an italics capable font enabled. for 381example, 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 387Normally, tmux enables the terminal's "alternate screen". Most terminals (such 388as xterm) do not save scrollback for the alternate screen. You might prefer 389tmux to use the normal screen, so it uses your terminal's scrollback 390buffer. This way, you can access the scrollback buffer as usual, for example 391using the mouse wheel - although there is no guarantee output inside tmux will 392always (or ever) be added to the scrollback. 393 394You can make tmux use the normal screen by telling it that your terminal does 395not have an alternate screen. Put the following in ~/.tmux.conf: 396 397 set -ga terminal-overrides ',xterm*:smcup@:rmcup@' 398 399Adjust if your $TERM does not start with xterm. 400 401tmux will still emulate the alternate screen for applications run under tmux, 402so you don't really lose anything with this setting. The only disadvantage is 403that when you exit tmux, it will not restore whatever was there before you 404started. 405 406* How do I see the default configuration? 407 408Show the default session options by starting a new tmux server with no 409configuration file: 410 411 $ tmux -Lfoo -f/dev/null start\; show -g 412 413Or 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 419When running in xterm(1), tmux can automatically send copied text to the 420clipboard. This is controlled by the set-clipboard option and also needs this 421X resource to be set: 422 423 XTerm*disallowedWindowOps: 20,21,SetXprop 424 425For rxvt-unicode (urxvt), there is an unofficial Perl extension here: 426 427 http://anti.teamidiot.de/static/nei/*/Code/urxvt/ 428 429Otherwise 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 433Or for inside and outside copy mode with the prefix key: 434 435 bind C-y run -b "tmux save-buffer - | xclip -i" 436 437On OS X, reattach-to-usernamespace lets pbcopy/pbpaste work: 438 439 https://github.com/ChrisJohnsen/tmux-MacOSX-pasteboard 440 441* Why do I see dots around a session when I attach to it? 442 443tmux limits the size of the window to the smallest attached session. If 444it didn't do this then it would be impossible to see the entire window. 445The dots mark the size of the window tmux can display. 446 447To avoid this, detach all other clients when attaching: 448 449 $ tmux attach -d 450 451Or from inside tmux by detaching individual clients with C-b D or all 452using: 453 454 C-b : attach -d 455