To start a virtual terminal session, run tmux. Your terminal window will show the command prompt and a green tmux status bar along the bottom, with information like the following:

[0] 0:ksh*        "caddis.blackhelicop" 11:55  26-Jun-13

This is a virtual terminal session. The left side of the status bar displays the tmux session number in brackets [0] and the list of tmux windows 0:ksh* (beginning with window number 0). The right side shows the first part of your machine name (caddis.blackhelicopters.org), followed by the time and date. You’ll learn how to customize things in Setting tmux Options and Configuring tmux.

The window name defaults to the name of the program running in that tmux(1) window. For example, if you start a command that continues until interrupted, such as iostat -w 5, the session name will change to match the command. Interrupt the command, return to a shell prompt, and the status bar should change its name to match your shell.

The status bar is normally green, but if it turns yellow, tmux is expecting input. When it’s yellow, any typing is interpreted as a tmux command. If you reach this mode accidentally, press ENTER to return to a green status bar and normal operation.

Pressing CTRL-B tells tmux that the next command is for tmux, not for the program running in the virtual terminal. (If pressing CTRL-B interferes with another program you use frequently, you can change this key combination, as you’ll see in Unmapping and Remapping Keys.)

The most commonly used tmux commands are single characters. For example, to create a second terminal window in this tmux session, press CTRL-B-C. Your screen will display only a command prompt and a new status bar.

[0] 0:iostat-  1:ksh*          "caddis.blackhelicopte" 11:58 26-Jun-13

You have two windows: window 0 shows iostat output, and window 1 displays the ksh prompt. The asterisk next to window 1 means that you’re currently looking at it. Run an ongoing command in your new window, such as top, and the window name should automatically change to the name of that command.

Press CTRL-B-? to see a complete list of all tmux commands.

  C-b: send-prefix
  C-o: rotate-window
  C-z: suspend-client
 Space: next-layout
   !: break-pane
   ": split-window
   #: list-buffers
…

Now you can easily explore tmux without reading the manual page. You’ll use this list to remap keys in Unmapping and Remapping Keys.

A collection of tmux windows is called a session. Conveniently, tmux can disconnect from a running session without interrupting its windows. Press CTRL-B-D to disconnect your terminal from the current tmux session. Your terminal should now show what it held before starting tmux. To reconnect to your tmux session, run tmux attach.

You can have multiple tmux sessions simultaneously. The session number appears on the far left of the status bar. (In our sample status bars, the tmux session is 0.)

To start a new tmux session without attaching to your previous session, run tmux without any arguments. For example, I type tmux instead of tmux attach in order to spawn a new tmux session when I want to pick up where I left off. You can change your tmux session within tmux itself, using a tmux command, but I usually just end the session and enter the correct command.

If you can have all these tmux sessions, how can you be sure that you haven’t left old, useless sessions lying around, with abandoned commands running in them? Use tmux list-sessions.

$ tmux list-sessions
0: 4 windows (created Sun Feb 13 12:17:14 2011) [80x23]
2: 1 windows (created Mon Feb 21 21:57:59 2011) [131x36] (attached)

I can see from the last line of this output that I left session 2 running on my other workstation, and am still attached to it.

To connect to session 2, use attach-session and option -t to choose a target session. Here, I attach to tmux session 2:

$ tmux attach-session -t 2

I’m now connected to the same session from two separate SSH sessions—in this case, from two separate client workstations. My typing in one screen is echoed on the other.

To destroy a session, use the kill-session command, specifying the session number with -t. Here, I kill tmux session 2:

$ tmux kill-session -t 2

Any programs running in windows in tmux session 2 will also be killed.

Command mode in tmux offers a prompt for entering more complicated commands. To enter command mode, press CTRL-B-:. The status bar will turn yellow, and a single colon replaces all window names. For example, to create a new window dedicated to running systat(1), press CTRL-B-: and enter neww systat. A window named systat will appear. Switch to that window, and then press CTRL-C to stop systat. That window will disappear.

You can do all sorts of things with tmux commands, including split windows into multiple panels, copy and paste text, and so on. (Read tmux(1) for the full list.) If you want to cut and paste from one window to another, it’s easiest if you use multiple terminal windows, but if you are working in a text-only console or another restricted environment, you might find these tmux features useful.

The tmux command mode is most commonly used to set options.

Options change how tmux windows, sessions, and the tmux server itself behave. The most common changes involve the appearance of windows, colors, or items displayed in the status bar. Some options affect the entire tmux session; others affect only a specific window. You can change options on the fly with the tmux command set-option.

Go ahead and open a tmux session to follow along. Press CTRL-B-: to enter command mode. When the colon appears, enter set-option status-fg green, and then press ENTER. Your status bar should now be solid green bar. Congratulations! You’ve set the status bar text color identical to the background color, making it unreadable. Return to command mode, and change the color to black to make it readable again. (If this bugs you, you can kill this tmux session and start a new one to reset all options.)

When making changes, use set-option (or just set) for options that affect the tmux server and the entire session. Use set-window-option (abbreviated setw) for options that affect only a single window.

Most people won’t need many (if any) tmux options, but they can prove useful. For example, say you want the status bar clock to display time in 24-hour format, or you want a visual bell instead of a beep. Options let you control these behaviors, as well as run commands in the status bar. To change basic tmux appearance and behavior, see the options in tmux(1).

Be sure to try any interesting options interactively. Once you have a tmux session running the way you like, enter show-options for an accurate list of the current options. Copy that list because we’ll use it to build a configuration file.

Modify $HOME/.tmux.conf in your home directory to configure your tmux sessions, or use /etc/tmux.conf to inflict your tmux preferences on every system user. Personal tmux configurations override global settings.

As a simple example, I’ve set the left side of my status bar (containing the session number) to blue, and the right side (the hostname, time, and date) to red. If I decide I like this, I can make this change permanent by entering the following in tmux.conf:

set -g status-left-bg blue
set -g status-right-bg red

The -g flag sets an option globally, so it takes effect for all sessions and windows.

This should get you comfortable with using tmux. If you need multiple terminal windows simultaneously, use a graphical desktop. Stay tuned.