Beginner’s guide to tmux

tmux is a terminal multiplexer. It allows you to run multiple command line commands on a single terminal. Never again will you need to open several terminals to execute a task or keep going back and forth between directories.

Installing tmux

tmux comes out of the box in some distributions. You can also install it by using most of the package management tool. There is the option to compile it yourself as well. Check out its installing wiki for more details.

Use cases

The tmux getting started states the main uses of tmux are:

• Protect running programs on a remote server from connection drops by running them inside tmux.
• Allow programs running on a remote server to be accessed from multiple different local computers.
• Work with multiple programs and shells together in one terminal, a bit like a window manager.

The first two uses are handy sometimes, but the third point is why you are always glad to be using tmux. With it you can organize your workspace into multiple sessions which can group related shells/commands.

Because of its key bindings, you can quickly find, create or close wanted shells without cycling between multiple terminals and with its copy mode you can browse command outputs or copy its content without using the mouse, allowing you to keep your hands on the keyboard at all times.

Key concepts

The tmux getting started goes over the basic concepts and terminology tmux uses. The main ones to understand are sessions, windows and panes. One session has windows and each window has panes. Panes are where shells or commands are run.

The prefix key is required to control tmux, usually all key presses are forwarded to the active pane on the current window. When the prefix key is pressed, tmux waits a combination of keys to execute before returning to forward keys to the active pane. The default prefix key is <C-b> (ctrl + b).

Knowing how to read the status line is also important, in it there is information about the session you are attached to, like its name, windows and the current window you are on.

Interacting with tmux

tmux has a lot of options and commands, the following sections present some of the commands and key bindings and by no means is an extensive display of all of its features.

Attaching clients

The first steps to interacting with tmux would be setting up a session in the server and attaching a client to it. This can be done by running:

$ tmux new-session -s <session-name>

<prefix> + d can be used to detach from the session.

To list the sessions on the server run:

$ tmux list-sessions

To attach to already running sessions use:

$ tmux attach-session -t <session>

list-keys and commands

You can check the current key bindings available by running <C-b> ? , every key binding is listed there. Key bindings mostly are composed of the key combination, the command triggered by the key binding and the key-table (consider it as a state) at which the combination triggers the command. Consider this default one as example:

bind-key -T prefix : command-prompt

This key binding is part of the prefix key-table, which represents the state after the prefix key is pressed, the combination is ‘:’ and after the combination is achieved it will run the command ‘command-prompt’ which prompts the user for a command.

Key bindings are simply shortcuts to commands, you could instead of using a key binding, write its command into the command prompt to produce the same result. So you can open the command prompt both by pressing <C-B> : or by typing ‘command-prompt’ into the command prompt, potentially going infinite if so is desired.

bind-key is itself a command that can be run to add or change key bindings. It can be run in the command prompt to affect the running server or added to the configuration file for future use.

Sessions

Separating related activities into different sessions can be beneficial as there are by default only 10 direct key bindings for selecting the windows in them.

By default there is no key binding for creating new session, you need to run the command new-session to create a new one.

<prefix> + $ is the default key binding to rename a session if necessary.

<prefix> + s lists the available session and allows you to attach to them.

Windows

A window is composed of an index and a name, it is usually identified by its index.

<prefix> + c creates a new window in the current session.

By default there are key bindings to select windows of index from 0 to 9 and it is of form <prefix> + <index>, <index> being the index of the window you want to switch.

To select windows with index higher than 9, there is also <prefix> + ‘ which prompts the user for an index to switch to.

<prefix> + n and <prefix> + p can be used to switch to next and previous windows, respectively.

<prefix> + & can be used to delete a window.

Panes

Panes can run different commands and are shown together as part of a window to the user. This is useful in many situations, like editing a source file and compiling or tailing logs.

<prefix> + % divides the current pane horizontally to create a new pane.

<prefix> + “ divides the current pane vertically to create a new pane.

<prefix> + o cycles the active pane through all of them.

<prefix> + q numbers the panes and pressing its number selects that pane as active.

<prefix> + x kills the current pane.

Rearranging or resizing the panes are sometimes handy, there are a lot of commands and shortcuts to do so, check out the list-keys for a list of them. One that you might execute by mistake is <prefix> + <C-o> when trying to cycle through the panes. This key binding rotates the panes.

Copy mode

Copy mode freezes the active pane allowing you to search and copy the output of some command to a tmux buffer. The key bindings to navegate in copy mode depends on the mode-key option, which is set as state by the manual:

mode-keys [vi | emacs]
          Use vi or emacs-style key bindings in copy mode. The default is emacs, unless VISUAL or EDITOR contains ‘vi’.

If mode-keys is set to emacs, then the copy-mode key-table will be used for key bindings when in copy mode, if it is vi, then the copy-mode-vi key-table will be used instead.

Regardless of the mode-keys used, copying a selection copies the content to a tmux buffer, it does not by default go to the OS clipboard.

Entering copy mode is achieved by using <prefix> + [ and pasting the most recent copy is done through <prefix> + ]. It is possible to paste previous copies by using <prefix> + =.

Copy mode is useful even if you do not intend to copy as it can be used to scroll up and down the terminal without using the mouse.

Configuration

tmux can be configured through configuration file. By default it uses ~/.tmux.conf. There are a lot of options to configure and they are listed in the manual but the defaults work reasonably well.

There are also a lot of tmux configuration repositories out there. One of the most popular is .tmux from gpakosz. It contains some useful features, like additional key bindings and ability to copy to OS clipboard. I personally disable the laptop battery status though.

Conclusion

This guide presented an introduction to some of tmux features to help anyone to start using it. Once you adopt it in your day to day activities you will not want to go back.

tmux is a very helpful tool for terminal users. It makes the experience of using command line tools much more pleasant with its key bindings and commands as well as being cool.

Consider playing with the default configuration for a while to get comfortable with the basic usage. Naturally you will start adding some key bindings or tinkering with configuration. Adopting popular configuration is also a good option, specially for features like copy to OS copyboard.