Getting Started

This tutorial takes about 15 minutes with a terminal open next to it. By the end you will have created a session, split it into panes, detached from it, come back to it, and written a small config file. Every key below is a tmux default, checked against tmux 3.7.

What tmux does

Normally, the programs you run belong to your terminal window. Close the window, or lose your SSH connection, and they stop. tmux changes that. It runs your shells inside its own background process, called the tmux server, and your terminal only shows them. You can disconnect, close the terminal app, even walk away to another computer, and everything keeps running.

tmux organizes your work in three layers:

• A session is a whole workspace, usually one per project. It keeps running in the background until you end it.
• A window is like a browser tab inside a session. Each one fills the screen.
• A pane is a split inside a window. Each pane is its own terminal running its own program.

So a session called api might have a window for your editor, another for the server, and a third split into two panes for tests and logs. The Core Concepts page explains these layers in depth.

Install tmux

tmux is in every major package manager. Pick the line for your system:

brew install tmux          # macOS (Homebrew)
sudo apt install tmux      # Debian, Ubuntu
sudo dnf install tmux      # Fedora
sudo pacman -S tmux        # Arch Linux

Then check that it works and see which version you have:

tmux -V

Distributions sometimes ship older versions. Everything on this page works on any recent tmux, but newer features such as floating panes need 3.7. The installation guide covers every platform, including Windows through WSL and building from source.

Start your first session

Create a session and give it a name:

tmux new -s learn

Your terminal clears and a green status bar appears at the bottom. That bar is how you know you are inside tmux. Reading from the left:

• [learn] is the session name.
• 0:zsh* is the window list: window number 0, running your shell (zsh, bash, or similar). The * marks the window you are looking at.
• On the right are the pane title (your computer's name by default) and the time and date.

Everything else works as normal. Run a few commands to see that this is still your usual shell.

The prefix key

To talk to tmux instead of the program in front of you, you press the prefix key first. The default is Ctrl+b. Press Ctrl and b together, let go, then press the command key.

For example, "Prefix + c" means: press Ctrl+b, release both keys, then press c.

Two shortcuts help while you learn:

• Ctrl+b then ? lists the default keys, each with a short note. Press q to close the list.
• Ctrl+b then / asks you to press a key, then tells you what it does.

Five things to try

Work through these in order inside your learn session.

1. Open a second window

Press Ctrl+b then c. The screen clears and the status bar now shows 0:zsh- 1:zsh*: window 1 is current (*) and window 0 was the last one you used (-).

Move between windows with Ctrl+b then the window number (0 or 1), or step through them with Ctrl+b then n (next) and p (previous).

2. Split the screen

Press Ctrl+b then %. The window splits into a left and a right pane. Now press Ctrl+b then " (double quote). The right pane splits into top and bottom. You now have three shells on one screen.

3. Move between panes and zoom

Press Ctrl+b then an arrow key to move to the pane in that direction. The active pane has a green border. Ctrl+b then o cycles through panes in order.

When you want one pane full screen for a moment, press Ctrl+b then z. A Z appears next to the window name. Press Ctrl+b then z again to put the layout back.

4. Detach

Start something that keeps running, so you can see it survive. In any pane, run:

top

Now press Ctrl+b then d. You are back in your normal shell, with a message like [detached (from session learn)]. The session is still running, top included. Check:

tmux ls

You should see a line like learn: 2 windows (created ...).

5. Reattach

Bring the session back:

tmux attach -t learn

Your windows, panes, and top are exactly where you left them. This detach-and-reattach cycle is the heart of tmux. On a remote server it means a dropped SSH connection costs you nothing: SSH back in and attach again. The SSH guide walks through that in detail.

Closing panes, windows, and sessions

• To close a pane, end its program. For a shell, type exit or press Ctrl+d. You can also press Ctrl+b then x, which asks for confirmation first.
• When the last pane in a window closes, the window closes. Ctrl+b then & closes the whole window after asking.
• When the last window closes, the session ends. To end a session from outside, run tmux kill-session -t learn.

Detaching and closing are different. Detaching (Ctrl+b then d) leaves everything running. Closing ends programs for good.

Scrolling back through output

New users often try to scroll with the mouse wheel and see odd results. By default tmux does not use the mouse, and your terminal's own scrollback only shows tmux redrawing the screen.

Use copy mode instead: press Ctrl+b then [, then scroll with the arrow keys or Page Up and Page Down. Press q to leave. Copy mode can also search and copy text, which the copy and paste guide explains. If you prefer the mouse, the config below turns it on.

A small starter config

tmux reads ~/.tmux.conf when the server starts. Create the file with these lines:

# Click to select panes, drag borders to resize, scroll with the wheel
set -g mouse on
 
# Keep more scrollback per pane (the default is 2000 lines)
set -g history-limit 50000
 
# Number windows and panes from 1, to match the keyboard
set -g base-index 1
setw -g pane-base-index 1

Apply it to the running server without restarting:

tmux source-file ~/.tmux.conf

The scrollback and numbering settings apply to new windows and panes, so open a new window to see them. When you want to go further, the configuration guide covers key bindings and the status bar, and the config generator builds a file for you.

Common first problems

• "sessions should be nested with care, unset $TMUX to force": you ran tmux inside tmux. Use Ctrl+b then s to switch sessions instead.
• "no server running on ...": there are no sessions yet, or they have all ended. Start one with tmux new -s name.
• Ctrl+b clashes with another program: some editors use Ctrl+b too. Many people move the prefix to Ctrl+a, shown in the configuration guide.
• Colors look wrong: see the troubleshooting guide, which covers terminal and color settings.

Where to go next

• Practice the keys in the interactive lessons until they become muscle memory.
• Keep the cheat sheet open in a tab.
• Look up any command in the command reference.