tmux frequently asked questions ****************************************************************************** * 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" or similar (such as "screen-256color"). * * Don't bother reporting problems where it isn't! * * * * Outside, it must match your terminal: particularly, use "rxvt" for rxvt * * and derivatives. * ****************************************************************************** * How is tmux different from GNU screen? tmux and GNU screen have many similarities. Some of the main differences I am aware of are (bearing in mind I haven't used screen for a few years now): - tmux uses a client-server model. Each server has single Unix domain socket in /tmp and within one server there are multiple sessions which may be attached to multiple clients (terminals). This has advantages, notably: windows may be linked simultaneously to multiple sessions; windows may be moved freely between sessions; and a client may be switched between sessions easily (C-b D). There is one major disadvantage: if the server crashes, game over, all sessions die. In practice, however, tmux is quite stable and gets more so as people report any bugs they hit :-). This model is different from screen, where typically each new screen instance is independent. tmux supports the same behaviour by using multiple servers with the -L option but it is not typically recommended. - Different command interfaces. One of the goals of tmux is that the shell should be easily usable as a scripting language - almost all tmux commands can be used from the shell and behave identically whether used from the shell, from a key binding or from the command prompt. Personally I also find tmux's command interface much more consistent and clearer, but this is subjective. - tmux calls window names (what you see in the status line) "names", screen calls them "titles". - tmux has a multiple paste buffers. Not a major one but comes in handy quite a lot. - tmux supports automatically renaming windows to the running application without gross hacks using escape sequences. Its even on by default. - tmux has a choice of vi or emacs key layouts. Again, not major, but I use emacs so if tmux did support only one key set it would be emacs and then all the vi users would get humpy. Key bindings may be completely reconfigured in any case. - tmux has an option to limit the window size. - tmux has search in windows (C-b f). - The window split (pane) model is different. tmux has two objects, windows and panes; screen has just windows. This difference has several implications: * In screen you can have a window appear in several layouts, in tmux a pane can only be in one window (fixing this is a big todo item but quite invasive). * tmux layouts are immutable and do not get changed unless you modify them. * In tmux, all panes are closed when you kill a window. * tmux panes do not have individual names, titles and so on. I think tmux's model is much easier to manage and navigate within a window, but breaking panes off from and joining them to windows is more clumsy. tmux also has support for preset pane layouts. - tmux's status line syntax is more readable and easier to use. I think it'd be hard for anyone to argue with this. tmux doesn't support running a command constantly and always using the last line of its output, commands must be run again each time. - tmux has modern, easily extended code. Again hard to argue screen is better if you have looked at the code. - tmux depends on libevent. I don't see this as a disadvantage: libevent is small and portable, and on modern systems with current package management systems dependencies are not an issue. libevent brings advantages in code simplicity and performance. - screen allows the window to be bigger than the terminal and can pan around it. tmux limits the size to the largest attached client. This is a big todo item for tmux but it is not trivial. - screen has builtin serial and telnet support; this is bloat and is unlikely to be added to tmux. - screen has support for updating utmp. Nobody has really come up with a clean, portable way to do this without making tmux setuid or setgid yet. - Environment handling is different. - tmux tends to be more demanding on the terminal so tends to show up terminal and application bugs which screen does not. - screen has wider platform support, for example IRIX and HP-UX, and for odd terminals. * I found a bug! What do I do? Please send bug reports by email to nicm@users.sourceforge.net or tmux-users@lists.sourceforge.net. Please include as much of the following information as possible: - the version of tmux you are running; - the operating system you are using and its version; - the terminal emulator you are using and the TERM setting when tmux was started; - a description of the problem; - if the problem is repeatable, the steps to repeat the problem; - for screen corruption issues, a screenshot and the output of "infocmp $TERM" from outside tmux are often very useful. * Why doesn't tmux do $x? Please send feature requests by email to nicm@users.sourceforge.net. * Why do you use the screen terminal description inside tmux? It sucks. It is already widely available. It is planned to change to something else such as xterm-xfree86 at some point, if possible. * I don't see any colour in my terminal! Help! On some 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. * tmux freezes my terminal when I attach to a session. I even have to kill -9 the shell it was started from to recover! Some consoles really really 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. * Why is C-b the prefix key? How do I change it? 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. It also has the advantage of not interfering with the use of C-a for start-of-line in emacs and the shell (although it does interfere with previous-character). Changing is simple: change the "prefix-key" 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 * How do I use UTF-8? When running tmux in a UTF-8 capable terminal, UTF-8 must be turned on in tmux; as of release 0.9, tmux attempts to autodetect a UTF-8-capable terminal by checking the LC_ALL, LC_CTYPE and LANG environment variables. list-clients may be used to check if this is detected correctly; if not, the -u command-line flag may be specified when creating or attaching a client to a tmux session: $ tmux -u new Since the 1.0 release, tmux will turn on UTF-8 related options automatically (ie status-utf8, and utf8) if the above conditions are met. * How do I use a 256 colour terminal? Provided the underlying terminal supports 256 colours, it is usually sufficient to add the following to ~/.tmux.conf: set -g default-terminal "screen-256color" Note that some platforms do not support "screen-256color" ("infocmp screen-256color" will return an error) - in this case see the next entry in this FAQ. tmux attempts to detect a 256 colour terminal both by looking at the colors terminfo entry and by looking for the string "256col" in the TERM environment variable. If both these methods fail, the -2 flag may be passed to tmux when attaching to a session to indicate the terminal supports 256 colours. * vim or $otherprogram doesn't display 256 colours. What's up? Some programs attempt to detect the number of colours a terminal is capable of by checking the colors terminfo or Co termcap entry. However, this is not reliable, and in any case is missing from the "screen" terminal description used inside tmux. There are two options (aside from using "screen-256color") to allow programs to recognise they are running on a 256-colour terminal inside tmux: - Manually force the application to use 256 colours always or if TERM is set to screen. For vim, you can do this by overriding the t_Co option, see http://vim.wikia.com/wiki/256_colors_in_vim. - Creating a custom terminfo file that includes colors#256 in ~/.terminfo and using it instead. These may be compiled with tic(1). * How do I make Ctrl-PgUp and Ctrl-PgDn work in vim? tmux supports passing through ctrl (and where supported by the client terminal, alt and shift) modifiers to function keys using xterm(1)-style key sequences. This may be enabled per window, or globally with the tmux command: setw -g xterm-keys on Because the TERM variable inside tmux must be set to "screen", vim will not automatically detect these keys are available; however, the appropriate key sequences can be overridden in .vimrc using the following: if &term == "screen" set t_kN=^[[6;*~ set t_kP=^[[5;*~ endif And similarly for any other keys for which modifiers are desired. Please note that the "xterm-keys" setting may affect other programs, in the same way as running them in a standard xterm; for example most shells do not expect to receive xterm(1)-style key sequences so this setting may prevent keys such as ctrl-left and ctrl-right working correctly. tmux also passes through the ctrl (bit 5 set, for example ^[[5~ to ^[[5^) modifier in non-xterm(1) mode; it may be possible to configure vim to accept these, an example of how to do so would be welcome. vim users may also want to set the "ttyfast" option inside tmux. * Why doesn't elinks set the window title inside tmux? There isn't a way to detect if a terminal supports setting the window title, so elinks attempts to guess by looking at the environment. Rather than looking for TERM=screen, it uses the STY variable to detect if it is running in screen; tmux does not use this so the check fails. A workaround is to set STY before running elinks. The following shell function does this, and also clears the window title on exit (elinks, for some strange reason, sets it to the value of TERM): elinks() { STY= `which elinks` $* echo -ne \\033]0\;\\007; } * What is the proper way to escape characters with #(command)? 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\)". * tmux uses too much CPU. What do I do? 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. * I use PuTTY and my tmux window pane separators are all qqqqqqqqq's! PuTTY is using a character set translation that doesn't support ACS line drawing. With a Unicode font, try setting PuTTY to use a different translation on the Window -> Translation configuration page. For example, change UTF-8 to ISO-8859-1 or CP437. It may also be necessary to adjust the way PuTTY treats line drawing characters in the lower part of the same configuration page. * What is the best way to display the load average? Why no #L? 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]}' * How do I attach the same session to multiple clients but with a different current window, like screen -x? 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. * Ctrl and arrow keys doesn't work in putty! What do I do? putty inverts the sense of the cursor key mode on ctrl, which is a bit hard for tmux to detect properly. To get ctrl keys right, change the terminfo settings so kUP5 (Ctrl-Up etc) are the adjusted versions, and disable smkx/rmkx so tmux doesn't change the mode. For example with this line in .tmux.conf (assuming you have TERM set to xterm): set -g terminal-overrides "xterm*:kLFT5=\eOD:kRIT5=\eOC:kUP5=\eOA:kDN5=\eOB:smkx@:rmkx@" Note that this will only work in tmux 1.2 and above. * How can I blank the tmux window? GNU screen has a feature whereby it will blank the screen after a period of inactivity. To do the same thing in tmux, use the lock-command setting, for example (with GNU bash): set -g lock-command 'tput civis && read -s -n1' This will remove the cursor and tell the shell to quit once a key has been pressed. For zsh, use "read -s -k1". In addition, it's possible to have both blanking and locking (for instance via lock(1) or vlock(1)) by using the following: bind x set lock-command '/usr/bin/vlock' \; lock-client \; set lock-command 'tput civis && read -s -n1' * How can I open a new window in the same directory as the current window? One option is to just run "TMUX= tmux" in the window. However, this only works if no command is running, so that you can input the command. A workaround is to let tmux know about the current path through an environment variable. To do so, use the following command: [ -n "$TMUX" ] && tmux setenv TMUXPWD_$(tmux display -p "#I") $PWD Which sets TMUXPWD_i (where i is the number of the current window) to the path of the current directory. This command can be added to PS1, for example: PS1='$([ -n "$TMUX" ] && tmux setenv TMUXPWD_$(tmux display -p "#I") $PWD)\h$ ' When a new window is created, the shell should be asked to change directory. You can define a new binding (for example, if using GNU bash): bind-key C-c run-shell 'tmux neww "cd $(tmux display -p "\$TMUXPWD_#I"); exec bash"' This solution will work even if a command is currently running in the terminal, but it will not work from a window that has just been swapped with another because TMUXPWD_i will not be updated after a swap. However, once a new prompt is displayed, TMUXPWD_i is updated properly. $Id: FAQ,v 1.40 2010-12-06 17:00:34 nicm Exp $