Annotation of embedaddon/tmux/FAQ, revision 1.1.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