Difference between revisions of "Tmux"

From ArchWiki
Jump to: navigation, search
m (Tips & Tricks: Tips and tricks)
(46 intermediate revisions by 25 users not shown)
Line 1: Line 1:
{{i18n|Tmux}}
+
[[es:Tmux]]
[[Category:Software]]
+
[[ru:Tmux]]
 
+
[[tr:Tmux]]
 +
[[Category:Terminal emulators]]
 
{{Article summary start}}
 
{{Article summary start}}
 
{{Article summary text|This article explains how to install and configure tmux.}}
 
{{Article summary text|This article explains how to install and configure tmux.}}
Line 7: Line 8:
 
{{Article summary wiki|GNU Screen}}
 
{{Article summary wiki|GNU Screen}}
 
{{Article summary end}}
 
{{Article summary end}}
 
 
[http://tmux.sourceforge.net/ Tmux] is a "terminal multiplexer: it enables a number of terminals (or windows), each running a separate program, to be created, accessed, and controlled from a single screen. tmux may be detached from a screen and continue running in the background, then later reattached."  
 
[http://tmux.sourceforge.net/ Tmux] is a "terminal multiplexer: it enables a number of terminals (or windows), each running a separate program, to be created, accessed, and controlled from a single screen. tmux may be detached from a screen and continue running in the background, then later reattached."  
  
Tmux is notable as a BSD-licensed alternative to [[Screen Tips|GNU Screen]]. Although similar, there are many differences between the programs, as noted on the [http://tmux.svn.sourceforge.net/viewvc/tmux/trunk/FAQ tmux FAQ page]. Most notably, tmux is currently under active development, in contrast to screen, which has not had a stable release since August 8, 2008.
+
Tmux is notable as a BSD-licensed alternative to [[Screen Tips|GNU Screen]]. Although similar, there are many differences between the programs, as noted on the [http://tmux.svn.sourceforge.net/viewvc/tmux/trunk/FAQ tmux FAQ page].
  
==Install==
+
==Installation==
 
[[pacman|Install]] {{Pkg|tmux}}, available in the [[Official Repositories]].
 
[[pacman|Install]] {{Pkg|tmux}}, available in the [[Official Repositories]].
  
==Configure==
+
==Configuration==
 
A user-specific configuration file should be located at {{ic|~/.tmux.conf}}, while a global configuration file should be located at {{ic|/etc/tmux.conf}}. Default configuration files can be found in {{Ic|/usr/share/tmux/}}.  
 
A user-specific configuration file should be located at {{ic|~/.tmux.conf}}, while a global configuration file should be located at {{ic|/etc/tmux.conf}}. Default configuration files can be found in {{Ic|/usr/share/tmux/}}.  
  
Line 69: Line 69:
  
 
===Browsing URL's===
 
===Browsing URL's===
To browse URL's inside tmux you must have urlview installed and configured:
+
To browse URL's inside tmux you must have {{aur|urlview}} installed and configured.
  bind-key u capture-pane \; save-buffer /tmp/tmux-buffer \; run-shell "$TERMINAL -e 'cat /tmp/tmux-buffer | urlview'"
+
 
 +
Inside a new terminal:
 +
  bind-key u capture-pane \; save-buffer /tmp/tmux-buffer \; run-shell "$TERMINAL -e urlview /tmp/tmux-buffer"
 +
 
 +
Or inside a new tmux window (no new terminal needed):
 +
bind-key u capture-pane \; save-buffer /tmp/tmux-buffer \; new-window -n "urlview" '$SHELL -c "urlview < /tmp/tmux-buffer"'
  
 
=== Setting the correct term===
 
=== Setting the correct term===
Line 104: Line 109:
 
Set scrollback to 10000 lines with  
 
Set scrollback to 10000 lines with  
 
  set -g history-limit 10000
 
  set -g history-limit 10000
 +
 +
=== Autostart with systemd ===
 +
 +
There are some notable advantages to starting a tmux server at startup.
 +
Notably, when you start a new tmux session, having the service already running reduces any delays in the startup.
 +
 +
Furthermore, any customization attached to your tmux session will be retained and your tmux session can be made to persist even if you have never logged in, if you have some reason to do that (like a heavily scripted tmux configuration or shared user tmux sessions).
 +
 +
The service below starts tmux for the specified user (eg. {{ic|tmux@main-user.service}})
 +
 +
{{hc|/etc/systemd/system/tmux@.service|<nowiki>
 +
[Unit]
 +
Description=Start tmux in detached session
 +
 +
[Service]
 +
Type=oneshot
 +
RemainAfterExit=yes
 +
KillMode=none
 +
User=%I
 +
ExecStart=/usr/bin/tmux new-session -s %u -d
 +
ExecStop=/usr/bin/tmux kill-session -t %u
 +
 +
[Install]
 +
WantedBy=multi-user.target
 +
</nowiki>}}
 +
 +
Alternatively, you may add {{ic|<nowiki>WorkingDirectory=%h</nowiki>}} and place this file within your [[Systemd/User]] directory, as {{ic|~/.config/systemd/user/tmux.service}} for a tmux service that starts when you log in.
  
 
==Session initialization==
 
==Session initialization==
Line 130: Line 162:
 
  bind B source-file ~/.tmux/bar
 
  bind B source-file ~/.tmux/bar
  
==Scrolling issues==
+
==Troubleshooting==
 +
===Scrolling issues===
 
If you have issues scrolling with Shift-PageUp/Shift-PageDown in your terminal, try this:
 
If you have issues scrolling with Shift-PageUp/Shift-PageDown in your terminal, try this:
  
 
  set -g terminal-overrides 'xterm*:smcup@:rmcup@'
 
  set -g terminal-overrides 'xterm*:smcup@:rmcup@'
 +
 +
=== Shift+F6 not working in Midnight Commander ===
 +
 +
If the {{ic|Shift+F6}} key combination is not working with either {{ic|1=TERM=screen}} or {{ic|1=TERM=screen-256color}}, then from inside tmux, run this command:
 +
infocmp > screen (or screen-256color)
 +
 +
Open the file in a text editor, and add the following to the bottom of that file:
 +
kf16=\E[29~,
 +
 +
Then compile the file with {{ic|tic}}. The keys should be working now.
  
 
==ICCCM Selection Integration==
 
==ICCCM Selection Integration==
Line 152: Line 195:
 
to this:
 
to this:
 
{{bc|bind C-p run "tmux save-buffer - <nowiki>|</nowiki> xclip -i -selection clipboard"}}
 
{{bc|bind C-p run "tmux save-buffer - <nowiki>|</nowiki> xclip -i -selection clipboard"}}
 +
 +
If the above doesn't work for you, try using xsel:
 +
 +
{{hc|~/.tmux.conf|
 +
...
 +
##CLIPBOARD selection integration
 +
##Requires prefix key before the command key
 +
#Copy tmux paste buffer to CLIPBOARD
 +
bind C-c run "tmux show-buffer <nowiki>|</nowiki> xsel -i -b"
 +
#Copy CLIPBOARD to tmux paste buffer and paste tmux paste buffer
 +
bind C-v run "tmux set-buffer -- \"$(xsel -o -b)\"; tmux paste-buffer"
 +
}}
 +
 +
It seems <code>xclip</code> does not close <code>STDOUT</code> after it has read from <code>tmux</code>'s buffer.  As such, <code>tmux</code> doesn't know that the copy task has completed, and continues to /await <code>xclip</code>'s termination, thereby rendering the window manager unresponsive. To work around this, you can execute the command via <code>run-shell -b</code> instead of <code>run</code>, you can redirect <code>STDOUT</code> of <code>xclip</code> to <code>/dev/null</code>, or you can use an alternative command like <code>xsel</code>.
 +
 +
===Urxvt MiddleClick Solution===
 +
{{Note|To use this, you need to enable mouse support|}}
 +
There is an unofficial perl extension (mentioned in the official [http://sourceforge.net/p/tmux/tmux-code/ci/master/tree/FAQ FAQ]) to enable copying/pasting in and out of urxvt with tmux via Middle Mouse Clicking.
 +
 +
First, you will need to download the perl script and place it into urxvts perl lib:
 +
 +
{{bc|wget http://anti.teamidiot.de/static/nei/*/Code/urxvt/osc-xterm-clipboard
 +
mv osc-xterm-clipboard /usr/lib/urxvt/perl/|
 +
}}
 +
 +
You will also need to enable that perl script in your .Xdefaults:
 +
{{hc|~/.Xdefaults|
 +
...
 +
*URxvt.perl-ext-common: osc-xterm-clipboard
 +
...
 +
}}
 +
 +
Next, you want to tell tmux about the new function and enable mouse support (if you haven't already). The third option is optional, to enable scrolling and selecting inside panes with your mouse:
 +
 +
{{hc|~/.tmux.conf|
 +
...
 +
set-option -ga terminal-override ',rxvt-uni*:XT:Ms<nowiki>=</nowiki>\E]52;%p1%s;%p2%s\007'
 +
set-window-option -g mode-mouse on
 +
set-option -g mouse-select-pane on
 +
...
 +
}}
 +
 +
That's it. Be sure to end all instances of tmux before trying the new MiddleClick functionality.
 +
 +
While in tmux, Shift+MiddleMouseClick will paste the clipboard selection while just MiddleMouseClick will paste your tmux buffer.
 +
Outside of tmux, just use MiddleMouseClick to paste your tmux buffer and your standard Ctrl-c to copy.
 +
 +
{{Note|The current tmux version 1.8-1 has a bug where it sometimes might not be possible to paste tmux buffer between different panes of tmux. This behaviour is fixed in the git-version (2013.10.15) |}}
  
 
==Tips and tricks==
 
==Tips and tricks==
Line 162: Line 253:
  
 
Simply add the following line of bash code to your .bashrc before your aliases; the code for other shells is very similar:
 
Simply add the following line of bash code to your .bashrc before your aliases; the code for other shells is very similar:
{{bc|<nowiki>[[ $TERM != "screen" ]] && tmux && exit</nowiki>}}
+
{{bc|<nowiki>[[ -z "$TMUX" ]] && exec tmux</nowiki>}}
  
{{hc|~/.bashrc|<nowiki># If not running interactively, do not do anything
+
{{hc|~/.bashrc|<nowiki>
 +
# If not running interactively, do not do anything
 
[[ $- != *i* ]] && return
 
[[ $- != *i* ]] && return
[[ $TERM != "screen" ]] && tmux && exit</nowiki>}}
+
[[ -z "$TMUX" ]] && exec tmux</nowiki>}}
  
{{note|At first you may read screen as if we were using screen and not tmux, but tmux also uses screen for the TERM enviroment variable.}}
+
{{note|This snippet ensures that tmux is not launched inside of itself (something tmux usually already checks for anyway). tmux sets $TMUX to the socket it is using whenever it runs, so if $TMUX isn't set or is length 0, we know we aren't already running tmux.}}
 +
 
 +
And this snippet start only one session(unless you start some manually), on login, try attach at first, only create a session if no tmux is running.
 +
 
 +
{{bc|<nowiki># TMUX
 +
if which tmux 2>&1 >/dev/null; then
 +
    #if not inside a tmux session, and if no session is started, start a new session
 +
    test -z "$TMUX" && (tmux attach || tmux new-session)
 +
fi</nowiki>}}
  
 
This snippet does the same thing, but also checks tmux is installed before trying to launch it. It also tries to reattach you to an existing tmux session at logout, so that you can shut down every tmux session quickly from the same terminal at logout.
 
This snippet does the same thing, but also checks tmux is installed before trying to launch it. It also tries to reattach you to an existing tmux session at logout, so that you can shut down every tmux session quickly from the same terminal at logout.
Line 183: Line 283:
  
 
{{note|Instead of using the bashrc file, you can launch tmux when you start your terminal emulator. (i. e. urxvt -e tmux)}}
 
{{note|Instead of using the bashrc file, you can launch tmux when you start your terminal emulator. (i. e. urxvt -e tmux)}}
 
===Split window and retain current directory===
 
 
{{Note|1=With [http://tmux.svn.sourceforge.net/viewvc/tmux?view=revision&revision=2647 revision 2647] this behavior became standard.}}
 
 
====Fast method====
 
 
{{Note|If you have set default-path to something for another convince; it will be reset to ~/}}
 
 
This command simply sets the default-path to your current path, splits the window, and resets it to your home directory. Can be easily bound to a key if you wish.
 
 
  tmux set default-path $(pwd) \; split-window\; set default-path ~/
 
 
To bind it to | and - respectively:
 
 
  bind - set default-path $PWD \; split-window\; set default-path ~/
 
  bind | set default-path $PWD \; split-window -v\; set default-path ~/
 
 
====cd method====
 
 
{{Note|This trick tries to inject a key into your session, which only works if it is at a command prompt (i. e. fails within a program like vim, emacs, …).}}
 
 
Create a excutable file as follows, for example {{ic|~/.scripts/tmux-split}}:
 
 
  #!/usr/bin/env bash
 
  PWD=`pwd`
 
  tmux split-window $1
 
  tmux send-keys " cd $PWD;clear"
 
  tmux send-keys "Enter"
 
 
and change the configure from:
 
 
  bind v split-window -h
 
  bind n split-window -v
 
 
to
 
 
  bind v send-keys " ~/mbin/split-tmux -h" \; send-keys "Enter"
 
  bind n send-keys " ~/mbin/split-tmux -v" \; send-keys "Enter"
 
 
====/proc method====
 
 
{{Note|This script, [http://chneukirchen.org/dotfiles/bin/tmux-neww-in-cwd borrowed from] Christian Neukirchen, reads the present pane's CWD from {{Ic|/proc/[pane's top program's $PID]/cwd}}. Some shells like zsh will not always properly update that entry.}}
 
 
Pasted into e. g. {{ic|~/.scripts/tmux-split-in-cwd}}:
 
 
#!/bin/sh
 
# tmux-split-in-cwd - open a new shell with same cwd as calling pane
 
 
SIP=$(tmux display-message -p "#S:#I:#P")
 
PTY=$(tmux server-info |
 
        egrep flags=\|bytes |
 
        awk '/windows/ { s = $2 }
 
              /references/ { i = $1 }
 
              /bytes/ { print s i $1 $2 } ' |
 
        grep "$SIP" |
 
        cut -d: -f4)
 
PTS=${PTY#/dev/}
 
PID=$(ps -eao pid,tty,command --forest | awk '$2 == "'$PTS'" {print $1; exit}')
 
DIR=$(readlink /proc/$PID/cwd)
 
 
case "$1" in
 
  h) tmux splitw -h "cd '$DIR'; $SHELL"
 
      ;;
 
  v) tmux splitw -v "cd '$DIR'; $SHELL"
 
      ;;
 
  *) tmux neww "cd '$DIR'; $SHELL"
 
      ;;
 
esac
 
 
{{ic|~/.tmux.conf}} could thus contain:
 
 
bind | run '~/.scripts/tmux-split-in-cwd h' # horizontal split in cwd
 
bind _ run '~/.scripts/tmux-split-in-cwd v' # vertical split in cwd
 
bind m run '~/.scripts/tmux-split-in-cwd' # new window in cwd
 
  
 
===Use tmux windows like tabs===
 
===Use tmux windows like tabs===
Line 272: Line 297:
 
Of course, those should not overlap with other applications' hotkeys, such as the terminal's. Given that they substitute terminal tabbing that might as well be deactivated, though.
 
Of course, those should not overlap with other applications' hotkeys, such as the terminal's. Given that they substitute terminal tabbing that might as well be deactivated, though.
  
It can also come handy to supplement the EOT hotkey {{Keypress|Ctrl}}+{{Keypress|d}} with one for tmux's detach:
+
It can also come handy to supplement the EOT hotkey {{ic|Ctrl+d}} with one for tmux's detach:
  
 
  bind-key -n C-j detach
 
  bind-key -n C-j detach
Line 282: Line 307:
 
{{Box||Screen and tmux's behaviour for when multiple clients are attached to one session differs slightly. In Screen, each client can be connected to the session but view different windows within it, but in tmux, all clients connected to one session must view the same window.
 
{{Box||Screen and tmux's behaviour for when multiple clients are attached to one session differs slightly. In Screen, each client can be connected to the session but view different windows within it, but in tmux, all clients connected to one session must view the same window.
  
This problem can be solved in tmux by spawning two separate sessions and synchronizing the second one to the windows of the first, then pointing a second new session to the first.
+
This problem can be solved in tmux by spawning two separate sessions and synchronizing the second one to the windows of the first, then pointing a second new session to the first.}}
 
+
However, this usage of tmux results in the problem that detaching from these mirrored sessions will start to litter your system with defunct sessions which can only be cleaned up with some pretty extreme micromanagement.}}
+
 
+
{{Note|Since tmux 1.4 mirrored sessions may be set to auto-destroy with the {{Ic|destroy-unattached}} session option}}
+
  
To avoid these issues he wrote the script “{{Ic|tmx}}” — the version below is slightly modified to execute “{{Ic|tmux new-window}}” if “1” is its second parameter. Invoked as {{Ic|tmx <base session name> [1]}} it launches the base session if necessary. Otherwise it will kill any “zombie” sessions, launch a new “client” session linked to the base, optionally add a new window and attach. Then it waits for detachment and kills its session.
+
The script “{{Ic|tmx}}” below implements this — the version here is slightly modified to execute “{{Ic|tmux new-window}}” if “1” is its second parameter. Invoked as {{Ic|tmx <base session name> [1]}} it launches the base session if necessary. Otherwise a new “client” session linked to the base, optionally add a new window and attach, setting it to kill itself once it turns “zombie”.
  
 
{{hc|tmx|2=<nowiki>
 
{{hc|tmx|2=<nowiki>
Line 324: Line 345:
 
     # Make sure we are not already in a tmux session
 
     # Make sure we are not already in a tmux session
 
     if [[ -z "$TMUX" ]]; then
 
     if [[ -z "$TMUX" ]]; then
        # Kill defunct sessions first
 
        old_sessions=$(tmux ls 2>/dev/null | egrep "^[0-9]{14}.*[0-9]+\)$" | cut -f 1 -d:)
 
        for old_session_id in $old_sessions; do
 
            tmux kill-session -t $old_session_id
 
        done
 
 
 
         echo "Launching copy of base session $base_session ..."
 
         echo "Launching copy of base session $base_session ..."
 
         # Session is is date and time to prevent conflict
 
         # Session is is date and time to prevent conflict
Line 340: Line 355:
 
tmux new-window
 
tmux new-window
 
fi
 
fi
         # Attach to the new session
+
         # Attach to the new session & kill it once orphaned
        tmux attach-session -t $session_id
+
tmux attach-session -t $session_id \; set-option destroy-unattached
        # When we detach from it, kill the session
+
        tmux kill-session -t $session_id
+
 
     fi
 
     fi
 
fi
 
fi
Line 353: Line 366:
  
 
added to {{ic|~/.tmux.conf}}. It causes tmux to resize a window based on the smallest client actually viewing it, not on the smallest one attached to the entire session.
 
added to {{ic|~/.tmux.conf}}. It causes tmux to resize a window based on the smallest client actually viewing it, not on the smallest one attached to the entire session.
 +
 +
An alternative taken from [http://sourceforge.net/mailarchive/forum.php?thread_name=CAPBqLKEC0MAFR%2BWUYqCuyd%3DKB47HK8CFSuAf%3Dd%3DW2H3F4fpMZw%40mail.gmail.com&forum_name=tmux-users] is to put the following ~/.bashrc:
 +
 +
{{hc|.bashrc|2=<nowiki>
 +
function rsc() {
 +
  CLIENTID=$1.`date +%S`
 +
  tmux new-session -d -t $1 -s $CLIENTID \; set-option destroy-unattached \; attach-session -t $CLIENTID
 +
}
 +
 +
function mksc() {
 +
  tmux new-session -d -s $1
 +
  rsc $1
 +
}
 +
</nowiki>}}
 +
 +
Citing the author:
 +
{{Box||"mksc foo" creates a always detached permanent client named "foo". It also
 +
calls "rsc foo" to create a client to newly created session. "rsc foo"
 +
creates a new client grouped by "foo" name. It has destroy-unattached
 +
turned on so when I leave it, it kills client.
 +
 +
Therefore, when my computer looses network connectivity, all
 +
"foo.something" clients are killed while "foo" remains. I can then call
 +
"rsc foo" to continue work from where I stopped.}}
  
 
===Changing the configuration with tmux started===
 
===Changing the configuration with tmux started===
Line 363: Line 400:
  
 
  bind r source-file <path>
 
  bind r source-file <path>
 +
 +
You can also do ^: and type :
 +
source .tmux.conf
  
 
===Template script to run program in new session resp. attach to existing one===
 
===Template script to run program in new session resp. attach to existing one===
Line 381: Line 421:
  
 
A derived version to run ''irssi'' with the ''nicklist'' plugin can be found on [[Irssi#irssi_with_nicklist_in_tmux|its ArchWiki page]].
 
A derived version to run ''irssi'' with the ''nicklist'' plugin can be found on [[Irssi#irssi_with_nicklist_in_tmux|its ArchWiki page]].
 +
 +
===Terminal emulator window titles===
 +
If you SSH into a host in a tmux window, you'll notice the window title of your terminal emulator remains to be {{ic|user@localhost}} rather than {{ic|user@server}}. To allow the title bar to adapt to whatever host you connect to, set the following in {{ic|~/.tmux.conf}}
 +
 +
set -g set-titles on
 +
set -g set-titles-string "#T"
 +
 +
For {{ic|set-titles-string}}, {{ic|#T}} will display {{ic|user@host:~}} and change accordingly as you connect to different hosts. You can also set many more options here.
 +
 +
===Automatic layouting===
 +
When creating new splits or destroying older ones the currently selected layout isn't applied. To fix that, add following binds which will apply the currently selected layout to new or remaining panes:
 +
 +
bind-key -n M-c kill-pane \; select-layout
 +
bind-key -n M-n split-window \; select-layout
  
 
== See also ==
 
== See also ==
 
* [http://mutelight.org/articles/practical-tmux Practical Tmux] by Brandur Leach, providing a number of configuration tips
 
* [http://mutelight.org/articles/practical-tmux Practical Tmux] by Brandur Leach, providing a number of configuration tips
 
* [http://www.openbsd.org/faq/faq7.html#tmux Tmux tutorial] section from the OpenBSD FAQ
 
* [http://www.openbsd.org/faq/faq7.html#tmux Tmux tutorial] section from the OpenBSD FAQ
 +
* [http://www.openbsd.org/cgi-bin/man.cgi?query=tmux OpenBSD Reference Manual for tmux]
 
* [http://www.dayid.org/os/notes/tm.html Screen and tmux feature comparison] page by Dayid Alan
 
* [http://www.dayid.org/os/notes/tm.html Screen and tmux feature comparison] page by Dayid Alan
 
* [http://blog.hawkhost.com/2010/06/28/tmux-the-terminal-multiplexer/ Tmux tutorial Part 1] & [http://blog.hawkhost.com/2010/07/02/tmux-%E2%80%93-the-terminal-multiplexer-part-2  Part 2] blog posts on Hawk Host
 
* [http://blog.hawkhost.com/2010/06/28/tmux-the-terminal-multiplexer/ Tmux tutorial Part 1] & [http://blog.hawkhost.com/2010/07/02/tmux-%E2%80%93-the-terminal-multiplexer-part-2  Part 2] blog posts on Hawk Host
 +
* [https://github.com/kooothor/.dotfiles/blob/master/.tmux.conf tmux.conf] example with CPU bar and shortcut to search man pages and display them vertically
 +
* [https://github.com/Lokaltog/powerline powerline] provides a powerful, dynamic statusbar configuration for tmux
  
 
'''Forum threads'''
 
'''Forum threads'''
 
* 2009-11-06 - Arch Linux - [https://bbs.archlinux.org/viewtopic.php?id=84157&p=1 Anyone loving Tmux in place of Screen? Info/Tips etc. URLs I've found]
 
* 2009-11-06 - Arch Linux - [https://bbs.archlinux.org/viewtopic.php?id=84157&p=1 Anyone loving Tmux in place of Screen? Info/Tips etc. URLs I've found]

Revision as of 18:14, 5 November 2013

Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary wiki Template:Article summary end Tmux is a "terminal multiplexer: it enables a number of terminals (or windows), each running a separate program, to be created, accessed, and controlled from a single screen. tmux may be detached from a screen and continue running in the background, then later reattached."

Tmux is notable as a BSD-licensed alternative to GNU Screen. Although similar, there are many differences between the programs, as noted on the tmux FAQ page.

Installation

Install tmux, available in the Official Repositories.

Configuration

A user-specific configuration file should be located at ~/.tmux.conf, while a global configuration file should be located at /etc/tmux.conf. Default configuration files can be found in /usr/share/tmux/.

Key bindings

Prefix all commands with Ctrl-b
Cmd Action
c Create a new window
n Change to next window
p Change to previous window
" Split pane horizontally
% Split pane vertically
, Rename current window
o Move to next pane

By default, command key bindings are prefixed by Ctrl-b. For example, to vertically split a window type Ctrl-b %.

After splitting a window into multiple panes, you can resize a pane by the hitting prefix key (i.e. Ctrl-b) and, while continuing to hold Ctrl, press Left/Right/Up/Down. Swapping panes is achieved in the same manner, but by hitting o instead of a directional key.

Tip: To mimic screen key bindings copy /usr/share/tmux/screen-keys.conf to either of the configuration locations.

Key bindings may be changed with the bind and unbind commands in tmux.conf. For example, you can change the prefix key (i.e. Ctrl-b) to Ctrl-a by adding the following commands in your configuration file:

unbind C-b
set -g prefix C-a

Additional ways to move between windows include:

Ctrl-b l (Move to the previously selected window)
Ctrl-b w (List all windows / window numbers)
Ctrl-b <window number> (Move to the specified window number, the default bindings are from 0 – 9)
Ctrl-b q  (Show pane numbers, when the numbers show up type the key to goto that pane)

What if you have 10+ windows open? Tmux has a find-window option & keybinding.

Ctrl-b f <window name> (Search for window name)
Ctrl-b w (Select from interactive list of windows)

Browsing URL's

To browse URL's inside tmux you must have urlviewAUR installed and configured.

Inside a new terminal:

bind-key u capture-pane \; save-buffer /tmp/tmux-buffer \; run-shell "$TERMINAL -e urlview /tmp/tmux-buffer"

Or inside a new tmux window (no new terminal needed):

bind-key u capture-pane \; save-buffer /tmp/tmux-buffer \; new-window -n "urlview" '$SHELL -c "urlview < /tmp/tmux-buffer"'

Setting the correct term

If you are using a 256 colour terminal, you will need to set the correct term in tmux. You can do this in either the tmux.conf:

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

or in your .bashrc with a test like:

# for tmux: export 256color
[ -n "$TMUX" ] && export TERM=screen-256color

If you enable xterm-keys in your tmux.conf, then you need to build a custom terminfo to declare the new escape codes or applications will not know about them. Compile the following with tic and you can use "xterm-screen-256color" as your TERM:

# A screen- based TERMINFO that declares the escape sequences
# enabled by the tmux config "set-window-option -g xterm-keys".
#
# Prefix the name with xterm- since some applications inspect
# the TERM *name* in addition to the terminal capabilities advertised.
xterm-screen-256color|GNU Screen with 256 colors bce and tmux xterm-keys,

# As of Nov'11, the below keys are picked up by
# .../tmux/blob/master/trunk/xterm-keys.c:
	kDC=\E[3;2~, kEND=\E[1;2F, kHOM=\E[1;2H,
	kIC=\E[2;2~, kLFT=\E[1;2D, kNXT=\E[6;2~, kPRV=\E[5;2~,
	kRIT=\E[1;2C,

# Change this to screen-256color if the terminal you run tmux in
# doesn't support bce:
	use=screen-256color-bce,

Other Settings

Set scrollback to 10000 lines with

set -g history-limit 10000

Autostart with systemd

There are some notable advantages to starting a tmux server at startup. Notably, when you start a new tmux session, having the service already running reduces any delays in the startup.

Furthermore, any customization attached to your tmux session will be retained and your tmux session can be made to persist even if you have never logged in, if you have some reason to do that (like a heavily scripted tmux configuration or shared user tmux sessions).

The service below starts tmux for the specified user (eg. tmux@main-user.service)

/etc/systemd/system/tmux@.service
[Unit]
Description=Start tmux in detached session

[Service]
Type=oneshot
RemainAfterExit=yes
KillMode=none
User=%I
ExecStart=/usr/bin/tmux new-session -s %u -d
ExecStop=/usr/bin/tmux kill-session -t %u

[Install]
WantedBy=multi-user.target

Alternatively, you may add WorkingDirectory=%h and place this file within your Systemd/User directory, as ~/.config/systemd/user/tmux.service for a tmux service that starts when you log in.

Session initialization

You can have tmux open a session with preloaded windows by including those details in your ~/.tmux.conf:

new  -n WindowName Command
neww -n WindowName Command
neww -n WindowName Command

To start a session with split windows (multiple panes), include the splitw command below the neww you would like to split; thus:

new  -s SessionName -n WindowName Command
neww -n foo/bar foo
splitw -v -p 50 -t 0 bar
selectw -t 1 
selectp -t 0

would open 2 windows, the second of which would be named foo/bar and would be split vertically in half (50%) with foo running above bar. Focus would be in window 2 (foo/bar), top pane (foo).

Note: Numbering for sessions, windows and panes starts at zero, unless you have specified a base-index of 1 in your .conf

To manage multiple sessions, source separate session files from your conf file:

# initialize sessions
bind F source-file ~/.tmux/foo
bind B source-file ~/.tmux/bar

Troubleshooting

Scrolling issues

If you have issues scrolling with Shift-PageUp/Shift-PageDown in your terminal, try this:

set -g terminal-overrides 'xterm*:smcup@:rmcup@'

Shift+F6 not working in Midnight Commander

If the Shift+F6 key combination is not working with either TERM=screen or TERM=screen-256color, then from inside tmux, run this command:

infocmp > screen (or screen-256color)

Open the file in a text editor, and add the following to the bottom of that file:

kf16=\E[29~,

Then compile the file with tic. The keys should be working now.

ICCCM Selection Integration

It is possible to copy a tmux paste buffer to an ICCCM selection, and vice-versa, by defining a shell command which interfaces tmux with an X11 selection interface. The following tmux config file snippet effectively integrates CLIPBOARD with the current tmux paste buffer using xclip:

~/.tmux.conf
...
##CLIPBOARD selection integration
##Requires prefix key before the command key
#Copy tmux paste buffer to CLIPBOARD
bind C-c run "tmux show-buffer | xclip -i -selection clipboard"
#Copy CLIPBOARD to tmux paste buffer and paste tmux paste buffer
bind C-v run "tmux set-buffer -- \"$(xclip -o -selection clipboard)\"; tmux paste-buffer"

If you get an output similar to \346\227\245\346\234\254\350\252\236\343\201\247 when pasting utf-8 characters, try changing this line:

bind C-c run "tmux show-buffer | xclip -i -selection clipboard"

to this:

bind C-p run "tmux save-buffer - | xclip -i -selection clipboard"

If the above doesn't work for you, try using xsel:

~/.tmux.conf
...
##CLIPBOARD selection integration
##Requires prefix key before the command key
#Copy tmux paste buffer to CLIPBOARD
bind C-c run "tmux show-buffer | xsel -i -b"
#Copy CLIPBOARD to tmux paste buffer and paste tmux paste buffer
bind C-v run "tmux set-buffer -- \"$(xsel -o -b)\"; tmux paste-buffer"

It seems xclip does not close STDOUT after it has read from tmux's buffer. As such, tmux doesn't know that the copy task has completed, and continues to /await xclip's termination, thereby rendering the window manager unresponsive. To work around this, you can execute the command via run-shell -b instead of run, you can redirect STDOUT of xclip to /dev/null, or you can use an alternative command like xsel.

Urxvt MiddleClick Solution

Note: To use this, you need to enable mouse support

There is an unofficial perl extension (mentioned in the official FAQ) to enable copying/pasting in and out of urxvt with tmux via Middle Mouse Clicking.

First, you will need to download the perl script and place it into urxvts perl lib:

wget http://anti.teamidiot.de/static/nei/*/Code/urxvt/osc-xterm-clipboard
mv osc-xterm-clipboard /usr/lib/urxvt/perl/

You will also need to enable that perl script in your .Xdefaults:

~/.Xdefaults
...
*URxvt.perl-ext-common:		osc-xterm-clipboard
...

Next, you want to tell tmux about the new function and enable mouse support (if you haven't already). The third option is optional, to enable scrolling and selecting inside panes with your mouse:

~/.tmux.conf
...
set-option -ga terminal-override ',rxvt-uni*:XT:Ms=\E]52;%p1%s;%p2%s\007'
set-window-option -g mode-mouse on
set-option -g mouse-select-pane on
...

That's it. Be sure to end all instances of tmux before trying the new MiddleClick functionality.

While in tmux, Shift+MiddleMouseClick will paste the clipboard selection while just MiddleMouseClick will paste your tmux buffer. Outside of tmux, just use MiddleMouseClick to paste your tmux buffer and your standard Ctrl-c to copy.

Note: The current tmux version 1.8-1 has a bug where it sometimes might not be possible to paste tmux buffer between different panes of tmux. This behaviour is fixed in the git-version (2013.10.15)

Tips and tricks

Start tmux in urxvt

Use this command to start urxvt with a started tmux session. I use this with the exec command from my .ratpoisonrc file.

urxvt -e bash -c "tmux -q has-session && exec tmux attach-session -d || exec tmux new-session -n$USER -s$USER@$HOSTNAME"

Start tmux on every shell login

Simply add the following line of bash code to your .bashrc before your aliases; the code for other shells is very similar:

[[ -z "$TMUX" ]] && exec tmux
~/.bashrc
# If not running interactively, do not do anything
[[ $- != *i* ]] && return
[[ -z "$TMUX" ]] && exec tmux
Note: This snippet ensures that tmux is not launched inside of itself (something tmux usually already checks for anyway). tmux sets $TMUX to the socket it is using whenever it runs, so if $TMUX isn't set or is length 0, we know we aren't already running tmux.

And this snippet start only one session(unless you start some manually), on login, try attach at first, only create a session if no tmux is running.

# TMUX
if which tmux 2>&1 >/dev/null; then
    #if not inside a tmux session, and if no session is started, start a new session
    test -z "$TMUX" && (tmux attach || tmux new-session)
fi

This snippet does the same thing, but also checks tmux is installed before trying to launch it. It also tries to reattach you to an existing tmux session at logout, so that you can shut down every tmux session quickly from the same terminal at logout.

# TMUX
if which tmux 2>&1 >/dev/null; then
    # if no session is started, start a new session
    test -z ${TMUX} && tmux

    # when quitting tmux, try to attach
    while test -z ${TMUX}; do
        tmux attach || break
    done
fi
Note: Instead of using the bashrc file, you can launch tmux when you start your terminal emulator. (i. e. urxvt -e tmux)

Use tmux windows like tabs

The following settings added to ~/.tmux.conf allow to use tmux windows like tabs, such as those provided by the reference of these hotkeys — urxvt's tabbing extensions. An advantage thereof is that these virtual “tabs” are independent of the terminal emulator.

#urxvt tab like window switching (-n: no prior escape seq)
bind -n S-down new-window
bind -n S-left prev
bind -n S-right next
bind -n C-left swap-window -t -1
bind -n C-right swap-window -t +1

Of course, those should not overlap with other applications' hotkeys, such as the terminal's. Given that they substitute terminal tabbing that might as well be deactivated, though.

It can also come handy to supplement the EOT hotkey Ctrl+d with one for tmux's detach:

bind-key -n C-j detach

Clients simultaneously interacting with various windows of a session

In “Practical Tmux”, Brandur Leach writes:

Template:Box

The script “tmx” below implements this — the version here is slightly modified to execute “tmux new-window” if “1” is its second parameter. Invoked as tmx <base session name> [1] it launches the base session if necessary. Otherwise a new “client” session linked to the base, optionally add a new window and attach, setting it to kill itself once it turns “zombie”.

tmx
#!/bin/bash

#
# Modified TMUX start script from:
#     http://forums.gentoo.org/viewtopic-t-836006-start-0.html
#
# Store it to `~/bin/tmx` and issue `chmod +x`.
#

# Works because bash automatically trims by assigning to variables and by 
# passing arguments
trim() { echo $1; }

if [[ -z "$1" ]]; then
    echo "Specify session name as the first argument"
    exit
fi

# Only because I often issue `ls` to this script by accident
if [[ "$1" == "ls" ]]; then
    tmux ls
    exit
fi

base_session="$1"
# This actually works without the trim() on all systems except OSX
tmux_nb=$(trim `tmux ls | grep "^$base_session" | wc -l`)
if [[ "$tmux_nb" == "0" ]]; then
    echo "Launching tmux base session $base_session ..."
    tmux new-session -s $base_session
else
    # Make sure we are not already in a tmux session
    if [[ -z "$TMUX" ]]; then
        echo "Launching copy of base session $base_session ..."
        # Session is is date and time to prevent conflict
        session_id=`date +%Y%m%d%H%M%S`
        # Create a new session (without attaching it) and link to base session 
        # to share windows
        tmux new-session -d -t $base_session -s $session_id
        if [[ "$2" == "1" ]]; then
		# Create a new window in that session
		tmux new-window
	fi
        # Attach to the new session & kill it once orphaned
	tmux attach-session -t $session_id \; set-option destroy-unattached
    fi
fi

A useful setting for this is

setw -g aggressive-resize on

added to ~/.tmux.conf. It causes tmux to resize a window based on the smallest client actually viewing it, not on the smallest one attached to the entire session.

An alternative taken from [1] is to put the following ~/.bashrc:

.bashrc
function rsc() {
  CLIENTID=$1.`date +%S`
  tmux new-session -d -t $1 -s $CLIENTID \; set-option destroy-unattached \; attach-session -t $CLIENTID
}

function mksc() {
  tmux new-session -d -s $1
  rsc $1
}

Citing the author: Template:Box

Changing the configuration with tmux started

By default tmux reads ~/.tmux.conf only if it was not already running. To have tmux load a configuration file afterwards, execute:

tmux source-file <path>

This can be added to ~/.tmux.conf as e. g.:

bind r source-file <path>

You can also do ^: and type :

source .tmux.conf

Template script to run program in new session resp. attach to existing one

This script checks for a program presumed to have been started by a previous run of itself. Unless found it creates a new tmux session and attaches to a window named after and running the program. If however the program was found it merely attaches to the session and selects the window.

#!/bin/bash

PID=$(pidof $1)

if [ -z "$PID" ]; then
    tmux new-session -d -s main ;
    tmux new-window -t main -n $1 "$*" ;
fi
    tmux attach-session -d -t main ;
    tmux select-window -t $1 ;
exit 0

A derived version to run irssi with the nicklist plugin can be found on its ArchWiki page.

Terminal emulator window titles

If you SSH into a host in a tmux window, you'll notice the window title of your terminal emulator remains to be user@localhost rather than user@server. To allow the title bar to adapt to whatever host you connect to, set the following in ~/.tmux.conf

set -g set-titles on
set -g set-titles-string "#T"

For set-titles-string, #T will display user@host:~ and change accordingly as you connect to different hosts. You can also set many more options here.

Automatic layouting

When creating new splits or destroying older ones the currently selected layout isn't applied. To fix that, add following binds which will apply the currently selected layout to new or remaining panes:

bind-key -n M-c kill-pane \; select-layout
bind-key -n M-n split-window \; select-layout

See also

Forum threads