From Gentoo Wiki
Jump to:navigation Jump to:search
Other languages:

Warning: Display title "tmux/en" overrides earlier display title "Tmux".


tmux (terminal multiplexer) is a program that enables a number of terminals (or windows), each running a separate program, to be created, accessed, and controlled from a single screen or terminal window. tmux may be detached from a screen and continue running in the background, then later reattached.[1] Users familiar with GNU Screen may find tmux as a good alternative.


USE flags

USE flags for app-misc/tmux Terminal multiplexer

debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
utempter Include libutempter support
vim-syntax Pulls in related vim syntax scripts


Install app-misc/tmux:

root #emerge --ask app-misc/tmux


Standard installation of tmux will not install a global (/etc/tmux.conf) or user (~/.tmux.conf) configuration file. Examples are provided in the {{Path|/usr/share/doc/tmux-{VERSION}/example_tmux.conf}} file and can be copied to a world or user location and edited as desired using a text editor.

Package examples

To see a list of configuration files, run the following command:

user $ls /usr/share/doc/tmux-2.0/examples
h-boetes.conf.bz2  n-marriott.conf.bz2  screen-keys.conf.bz2  t-williams.conf.bz2  vim-keys.conf.bz2

Then use cp to move one of the files to either the global location (which will affect all users) or to the user's home directory.

Wiki example

The following is an example ~/.tmux.conf file:

FILE ~/.tmux.conf
set -g default-terminal "screen-256color"   # Use 256 colors
set -g history-limit 100000                 # Scrollback buffer number of lines
# Start window indexing at one instead of zero
set -g base-index 1
# Set the prefix key and some key bindings to match GNU Screen
set -g prefix C-a
bind-key C-a last-window
# Key bindings for horizontal and vertical panes
unbind %
bind | split-window -h
bind - split-window -v
# Enable window titles
#set -g set-titles on
# Window title string (uses statusbar variables)
set -g set-titles-string '#T'
# Status bar with load and time
set -g status-bg '#4e4e4e'
set -g status-fg '#ffffff'
set -g status-left ' '
set -g status-right '#[bg=#bbbbbb]#[fg=#000000]#(cut -d " " -f -3 /proc/loadavg) #[bg=#4e4e4e]#[fg=#ffffff]#(
date +" %H:%M ")'
set -g window-status-format '#I #W'
set -g window-status-current-format ' #I #W '
setw -g window-status-current-bg '#55ff55'
setw -g window-status-current-fg '#000000'
# Pane border colors
set -g pane-active-border-fg '#bbbbbb'
set -g pane-border-fg '#555555'
# Bind to reload config
bind r source-file ~/.tmux.conf


A few plugins are available for tmux. See the sections below for available options.


tmux-mem-cpu-load is a small program designed to monitor system activity in the status line of tmux. See the tmux-mem-cpu-load sub-article for more details on the installation process.

Tmux Resurrect

tmux-resurrect persists tmux environments across system restarts. See the resurrect sub-article for more details on the installation process.


Key bindings

tmux can be controlled from an attached client by using a key combination of a prefix key stroke (Ctrl+b by default) followed by a command key.

After pressing Ctrl+B the following key combinations can be used:


  • ? = List all key bindings.
  • d = Detach the current client.
  • : = Enter the tmux command prompt.

Creating and managing windows

  • c = Create a new window
  • n = Change to the next window.
  • p = Change to the previous window.
  • l = Move to the previously selected window.
  • 0-9 = Select windows 0 to 9.
  • ' = Prompt for a window index to select. Then enter a number or title to switch to that window.
  • , = Rename the current window.
  • w = Choose the current window interactively.
  • :, then type list-windows enter = Display the list of windows.

Creating and managing panes

  • " = Split the current pane into two, top and bottom.
  • % = Split the current pane into two, left and right.
  • o = Select the next pane in the current window.
  • ; = Move to the previously active pane.
  • { = Swap the current pane with the previous pane.
  • } = Swap the current pane with the next pane.
  • Ctrl+o = Rotate the panes in the current window forwards.
  • Alt+1 to Alt+5 = Arrange panes in one of the five preset layouts: even-horizontal, even-vertical, main-horizontal, main-vertical, or tiled.
  • x = Kill the current pane.
  • ! = Break the current pane out of the window.

Copy, paste, and scroll operations

The keys available depend on whether emacs (default) or vi mode is selected. The mode-keys option can be set in .tmux.conf for vi mode.

  • [ = Enter copy mode to copy text or view the history.
  • ] = Paste the most recently copied buffer of text.
  • # = List all paste buffers.
  • - = Delete the most recently copied buffer of text.

Session control

Start session

Once started tmux creates a socket for the session in /tmp/S-<UID>/<Session Name>

tmux can be started with the following command:

user $tmux

Or, to give the session a name on start up, run:

user $tmux new-session -s portage

Listing sessions

List tmux sessions to see existing session information:

user $tmux ls
0: 1 windows (created Thu Apr  9 09:09:03 2015) [180x65] (attached)

When listing sessions the name of the session should appear as the first item in the session information line. It is possible to see from the output above the session was created without a name, hence the session is to be referenced as 0.

Another way to list sessions is by typing out the long list-sessions argument.

user $tmux list-sessions
0: 1 windows (created Thu Apr  9 09:09:03 2015) [180x65] (attached)

The exact same output as the previous list command is displayed.

Renaming a session

Simply using tmux to start a session will not provide the session with a nice, human readable name.

If the default session name is not descriptive enough (0 does not tend to describe much), then a session can be renamed. Suppose Larry the cow started tmux without specifying a session name on start up. He begins working on compiling a new version of Portage, and wants to change the session name to reflect his current task. To change the session name he would first assume control of tmux by pressing the magic key stroke: Ctrl+b, then : which will drop focus into the tmux control line. By default the line should turn yellow. Once there he would issue:

:rename-session -t 0 portage

Where 0 is the existing (default) session name and portage is the desired new name for the session. To rename when detached from a tmux session issue:

user $tmux rename-session -t 0 portage

Resuming a session

After the session is detached, all the active terminals remain active and so do commands that did not finish yet. To resume a session use attach -t <session_name>.

user $tmux a -t portage

Or use the long way of attaching to an existing session:

user $tmux attach -t portage

Daemon-like operation

To start a command in a tmux session without attaching to the session (like a daemon) use new-session -d followed by the command to execute in quotes:

user $tmux new-session -d 'emerge -uDNvp @world'

See also

  • Screen - An alternative to tmux.

External resources