Knowledgebase

Introduction

Tmux is a terminal multiplexer. It allows you to run and manage several command prompts simultaneously from one tmux session.

Tmux uses a client/server model, which allows it to persist connections. You can start a session from one computer, run several programs running in it, and then disconnect. You can later reconnect to the same session from a different computer and the same programs will be running.

Install tmux on Debian and Ubuntu

On Debian and Ubuntu systems, install tmux with apt.

$ sudo apt-get update && sudo apt-get -y install tmux

Install tmux on Redhat, CentOS, and Other RHEL-Based Distributions

On Redhat, CentOS, and other RHEL-based systems, install tmux with yum.

$ sudo yum install update && sudo yum -y install tmux

Terminology

• Pane - A pane is simply a terminal prompt.

• Window - A window holds multiple panes (terminals) on one screen.

• Session - A session has multiple windows.

• Server - A server holds multiple sessions. It runs in the background and ensures the persistence of the sessions.

Start a New tmux Session

$ tmux new -s start

You will see a bar at the bottom of the screen with the session name tmux created, start, in brackets. This is because tmux automatically logs in with your user account when it creates new panes.

Maneuvering in tmux

Once inside a tmux session, you use a prefix key to trigger commands to tell tmux what to do. The default prefix key is CTRL + B. For example, if you want to tell tmux to create a new pane by splitting your screen into two vertical sections, you first type CTRL + B, then %.

Create Multiple Panes

If you typed CTRL + B, then % as shown above, then you have two panes on your screen.

• Split the current pane into two horizontal sections by typing CTRL + B, then ".

• To cycle through all three panes, type CTRL + B, then O.

Switch Between Panes

To switch between different open panes, use the arrow keys with the prefix.

• CTRL + B, then UP: Go to the pane above the current pane.

• CTRL + B, then DOWN: Go to the pane below the current pane.

• CTRL + B, then LEFT: Go to the pane on the left of the current pane.

• CTRL + B, then RIGHT: Go to the pane on the right of the current pane.

Create Multiple Windows

1. Create a new window in the start session. Type CTRL + B, then C to open a new blank terminal.

2. Split this terminal into two horizontal panes with CTRL + B, then ".

3. Create a third window with CTRL + B, then C.

   You will see a new blank terminal again.

4. Issue the command tmux list-windows, then press ENTER to confirm that you have three windows opened.

5. Use CTRL + B, then N to cycle between the three windows created.

Attach and Detach to/from a Session

• Use CTRL + B, then D to detach from your current session.

• Reconnect to your session with tmux attach -t YOUR_SESSION_NAME.

• Use CTRL + B, then N to cycle between the windows in your session.

Common Key Bindings

• CTRL + B, then C : Create new window.

• CTRL + B, then , : Rename a window.

• CTRL + B, then N : Move to the next window.

• CTRL + B, then P : Move to the previous window.

• CTRL + B, then & : Kill current window.

• CTRL + B, then % : Split current pane into two (vertically).

• CTRL + B, then " : Split current pane into two (horizontally).

• CTRL + B, then O : Switch to next pane.

• CTRL + B, then Q : Show pane numbers (then type a # to switch to it).

• CTRL + B, then D : Detach from current session.

• CTRL + B, then ? : List all key bindings.

• CTRL + B, then X: Kill the active pane (after pressing Y to confirm).

• CTRL + B, then W: Show an overview of all active windows and panes. Use the arrow keys to move through the list of windows and see a preview of the selected window. Press ENTER to switch to the selected window. Press ESC to exit the overview.

Common Commands

• tmux list-sessions - List existing tmux sessions.

• tmux new -s session-name - Create a new tmux session named session-name.

• tmux attach -t session-name - Connect to an existing tmux session named session-name.

• tmux switch -t session-name - Switches to an existing tmux session named session-name.

Use Vim Key Bindings to Switch Between Panes

Instead of using the arrow keys to switch between different panes, you can use the Vim keys H, J, K, L. To do this, update the tmux configuration file ~/.tmux.conf. If this file doesn't exist, create it.

Add these lines (the first line is a comment) to the configuration file to enable pane navigation using Vim keys:

# hjkl pane traversal

bind h select-pane -L

bind j select-pane -D

bind k select-pane -U

bind l select-pane -R

After updating the configuration file, restart tmux. You can load the new configuration without restarting tmux by sourcing the updated configuration file:

tmux source-file ~/.tmux.conf

The Meta Key

Many of the key bindings in the following sections are based on the Meta key. On most modern computers and keyboards, the Meta key is not one specific key. Depending on the system settings and the terminal emulator in use, the Meta key could be bound to either ESC, ALT, COMMAND, WIN, or Opt. Where you see META as part of a key binding, try using the ESC key. If it doesn't work, try one of the other keys mentioned above.

Adjust Pane Size

When a window has multiple panes, you can change the size of individual panes.

• To change the pane size, press and hold the prefix (CTRL + B), and simultaneously press one of the arrow keys.

• Hold down CTRL + B, and simultaneously press either UP or DOWN: Change the height of the pane.

• Hold down CTRL + B, and simultaneously press either LEFT or RIGHT: Change the width of the pane.

The above key combinations resize the pane "continuously" as long as they are held pressed. To resize the pane one step at a time:

• CTRL + B, then META + either UP or DOWN: Change the height of the pane.

• CTRL + B, then META + either LEFT or RIGHT: Change the width of the pane.

Whether a particular key combination (above) increases or decreases the dimensions of the pane depends on the positioning of that pane relative to other panes.

If the terminal emulator supports mouse use, you can resize panes by dragging their borders.

Choose a Preset Pane Layout

Tmux has five different preset layouts for arranging multiple panes in a window:

1. All panes are stacked side-by-side.

2. All panes are stacked on top of each other.

3. The main pane takes up the entire screen width and the other panes are stacked side-by-side below it

4. The main pane takes up the entire screen height and the others panes are stacked beside it on top of each other

5. All panes are arranged in a grid.

Start tmux and create 4 (or any number of) panes.

To cycle through the different preset layouts use CTRL + B, then SPACE

You can also choose a specific layout:

• CTRL + B, then META + 1: Switch to layout 1.

• CTRL + B, then META + 2: Switch to layout 2.

• CTRL + B, then META + 3: Switch to layout 3.

• CTRL + B, then META + 4: Switch to layout 4.

• CTRL + B, then META + 5: Switch to layout 5.

Swapping Pane Positions

When a window has multiple panes, you can move the panes around and swap their positions.

Note: As described previously, CTRL + B, then O cycles the cursor through the different panes. The above sequence is for cycling the positions of the panes themselves.

• CTRL + B, then META + O cycles the positions of the panes clockwise.

• CTRL + B, then CTRL + O cycles the positions of the panes counterclockwise.

Detach and Reattach Individual Panes

In a layout with multiple panes in a window, it is sometimes necessary to move a pane to a different location. Swapping pane positions (as described above) isn't always sufficient, because it disturbs the positions of all the other panes. It is also sometimes necessary to move a pane to a different window in the same session.

Use the command break-pane in the tmux command prompt to detach a pane from the window. join-pane reattaches the pane.

To access the tmux command prompt, press the prefix CTRL + B, then press :. This will open up a prompt at the bottom of the terminal. To exit it without entering any commands, press CTRL + C.

To detach a pane, switch to the pane to be detached, activate the tmux command prompt (CTRL + B, then :), and enter the command:

break-pane -dP

This will detach the active pane and show its "ID". This ID is of the format X:Y.Z where X, Y, and Z are numbers. The previous pane becomes the new active pane. The ID is shown on top of the (new) active pane. Note down this ID and then dismiss it by pressing ESC.

The detached pane can be reattached next to any pane in any window in the same session. Switch to the pane next to which you want to reattach the detached pane. Activate the tmux command prompt and enter:

join-pane -vs X:Y.Z

This reattaches the detached pane below the active pane (vs stands for vertical split). To reattach the detached pane on the right side of the active pane:

join-pane -hs X:Y.Z

In the above command, hs stands for horizontal split.

Share tmux Sessions Between Users

How Sessions Work

When you start tmux, it creates a new server instance and creates a session within that server.

Tmux clients and servers are separate processes. They communicate via a UNIX socket. By default, tmux stores sockets in the /tmp directory. Sockets for servers created by an individual user are stored under a subdirectory named tmux-UID where UID is the UNIX UID of that user. A user whose UID is 1001 will have its sockets stored in /tmp/tmux-1001. The owner of this subdirectory is user1. By default, no other user or group can access this subdirectory.

Compatibility

The steps described in this section have been tested on tmux versions 3.1 and 3.3 on a vanilla Debian 11 installation. They should be applicable to all recent tmux versions.

Note: On security-hardened Operating Systems, such as those involving SELinux, changing groups and permissions can need additional steps. Discussing those is beyond the scope of this guide. It is assumed you know how to change groups and permissions on your Operating System.

Tmux version 3.3 (released in June 2022) introduced security related changes in the way session sharing works. These changes involve the use of the newly added server-access command. Check the version of your tmux installation using tmux -V. In practice, this leads to one additional step for tmux versions 3.3 and higher.

System Description

Consider a system with two users: user1 with UID 1001 and user2 with UID 1002.

In order for user2 to connect to tmux sessions created by user1, user2) must have access to the socket of the server created by user1 so that clients created by user2 can communicate with the server created by user1, and (for versions 3.3 and higher) have access to the server, granted by user1 with the server-access command.

In following the steps below, use the appropriate user IDs and usernames based on your own system. Check the UID (and other details) of a user user1:

$ id user1

The command id without any parameters shows the UID (and other details) of the current user.

If there are no additional user accounts on your system, create a new user before testing these steps.

Steps

The steps below describe how user1 can grant access to its tmux sessions to user2.

1. In a terminal session, log in as user1.

2. Start a tmux session:

   $ tmux
   

   This will create the socket (sub)directory if it did not previously exist.

3. Check the ownership and permissions for the socket directory:

   $ ls -hdl /tmp/tmux-1001
   

4. Create a common group for user1 and user2, this will make it easier to manage permissions. Create a new group tmuxusers:

   # groupadd tmuxusers
   

5. Add user1 and user2 to this group:

   # usermod -a -G tmuxusers user1
   
   # usermod -a -G tmuxusers user2
   

6. Change the group of the /tmp/tmux-1001 directory to tmuxusers:

   # chgrp -R tmuxusers /tmp/tmux-1001 
   

7. user2 needs full access to the sockets of tmux servers started by user1. Give the group full permissions on the directory:

   # chmod -R g+rwx /tmp/tmux-1001
   

8. Verify that the group of the directory has been changed to tmuxusers and that the group has full permissions on the directory:

   $ ls -hdl /tmp/tmux-1001
   

9. Exit the running tmux session:

   $ exit
   

10. As user1 (again), create a new tmux session and specify the name of the socket:

    $ tmux -L socket1
    

11. The -L option creates a named socket socket1, with the path /tmp/tmux-1001/socket1.

12. All commands so far are applicable on all recent versions of tmux. The next 3 commands are only for tmux version 3.3 and higher.

    1. Within the newly created tmux session, give user2 access to the tmux server:

       $ tmux server-access -w -a user2
       

    2. The above command gives user2 write access to the session. So, user2 can also enter commands in the session. It is possible to give user2 only read access. With read access, user2 can only view the contents of the session but cannot enter any commands. To give user2 read access, use -r instead of -w in the above command:

       $ tmux server-access -r -a user2
       

    3. user1 can revoke the permissions granted to user2:

       $ tmux server-access -d user2
       

    The previous three commands are only for tmux version 3.3 and higher. Further steps are applicable to all recent versions of tmux.

13. Change the group of the new socket file:

    # chgrp tmuxusers /tmp/tmux-1001/socket1
    

14. Verify that the group of the socket file is tmuxusers and that group has access to the file:

    # ls -l /tmp/tmux-1001/socket1
    

15. Check the ID(s) of the open session(s):

    $ tmux ls
    

16. In another terminal, log in as user2. Start tmux and specify the path of the named socket created by user1:

    $ tmux -S /tmp/tmux-1001/socket1 ls
    

    The above command shows the list of sessions on the server started by user1 and listening on socket1.

17. Attach to the session:

    $ tmux -S /tmp/tmux-1001/socket1
    

18. If there are many open sessions, attach to a specific session (whose ID is N):

    $ tmux -S /tmp/tmux-1001/socket1 attach -t N
    

user2 is now connected to the tmux session of user1.

Using Nested Sessions

In general, using nested sessions in tmux is neither necessary nor recommended. It is, however, useful when connecting to a remote tmux session from within a local tmux session. Suppose you are in a tmux session on the local computer. In one of the panes (or windows), you log in to a remote server which also has running tmux sessions. When you connect to a tmux session on this remote server, you end up with nested sessions. The remote tmux session is nested inside the local tmux session.

To pass a key sequence to the nested session, consecutively press the prefix key combination for both sessions. Assuming that both sessions use the default prefix key, press CTRL+B twice to access the nested session.

For example, to do a vertical split in the nested session, enter: CTRL+B, followed by (again), CTRL+B, then %.

More Information

• You can extend tmux with tools like teamocil and tmuxifier.

• Please see the tmux documentation for more details.