Panes: Splitting a Window Into Multiple Shells | tmux Tutorial

What a Pane Is

A pane is a rectangle of your terminal that holds one shell or program. A window is made of one or more panes arranged in a grid. You can split any pane into two, then split those, and end up with an editor on the left, a shell in the top right, and a log tail in the bottom right.

Every pane runs its own process. Closing a pane kills its process tree. Detaching from the session leaves every pane running.

Splitting

<prefix> "                   split current pane horizontally (new pane below)
<prefix> %                   split current pane vertically (new pane to the right)

These defaults are famously confusing because " looks like a horizontal divider, but it creates a horizontal split, which means two panes stacked one above the other with a horizontal line between them. Many people rebind these:

bind | split-window -h
bind - split-window -v

| for side-by-side, - for over/under. Now the key suggests the line between panes, which is easier to remember. Covered in chapter 7.

Splitting with options

<prefix> :split-window -h          vertical split (new pane on the right)
<prefix> :split-window -v          horizontal split (new pane below)
<prefix> :split-window -c ~/code   split and start in ~/code
<prefix> :split-window -p 30       split, new pane takes 30% of the space
<prefix> :split-window -f          split the entire window, not just the current pane

-f is useful when you want a full-width split across a window that already has columns. Without it, the split only divides the current column.

<prefix> o                   cycle to the next pane
<prefix> ;                   toggle to the last pane you were in
<prefix> Up Down Left Right  move focus in that direction
<prefix> q                   briefly show pane numbers; press a number to jump

<prefix> q is underrated. It flashes a number on each pane (like 0, 1, 2) for a second. Press that number and you jump to that pane.

Most people bind vim-style pane navigation:

bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

Now <prefix> h/j/k/l moves focus. Combined with the vim-tmux-navigator plugin, the same keys cross into editor splits without thinking (chapter 11).

Resizing

<prefix> Alt-Up/Down/Left/Right    resize in that direction (1 cell)
<prefix> Ctrl-Up/Down/Left/Right   resize by 5 cells
<prefix> :resize-pane -D 10        down by 10
<prefix> :resize-pane -x 80        set width to 80 columns

The Alt-bindings need prefix each time by default. Rebind them with -r (repeat) to press prefix once and resize repeatedly:

bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5

Now <prefix> J J J shrinks down by 15 cells total. -r means "within repeat-time, repeat presses count without re-pressing prefix".

Zoom

<prefix> z                   zoom: the current pane fills the window. Press again to unzoom

Zoom is the single most useful pane command. You're working in a multi-pane layout and want to focus on one pane for a while. Zoom it. Come back. Layout restored.

The status bar shows a Z next to the window name when a pane is zoomed. Remember to unzoom before running prefix o; the other panes still exist, they're just hidden.

Swapping Panes

<prefix> {                   swap current pane with the previous one
<prefix> }                   swap with the next one
<prefix> :swap-pane -t 2     swap current with pane 2

Useful when the layout put a pane in the wrong spot. Swap is fast and keeps pane identities (running processes stay put).

Closing Panes

exit                         close the current pane by exiting the shell

Or:

<prefix> x                   kill the current pane (prompts for confirmation)

When you close the last pane in a window, the window closes. When you close the last window in a session, the session closes.

Layouts

A layout is an arrangement of panes. tmux has five built-in:

<prefix> M-1                 even-horizontal: all panes in one row
<prefix> M-2                 even-vertical: all panes in one column
<prefix> M-3                 main-horizontal: one big pane on top, rest below
<prefix> M-4                 main-vertical: one big pane on the left, rest on the right
<prefix> M-5                 tiled: grid-ish auto layout

(M- means Alt, also written as Meta.)

And a cycle:

<prefix> Space               cycle through the layouts

The main-vertical layout is popular for editor-plus-shells workflows: editor on the left half, two shells stacked on the right.

Saving and restoring custom layouts

<prefix> :display -p '#{window_layout}'

tmux prints the current layout as an opaque string, something like:

b25d,204x50,0,0{136x50,0,0,1,67x50,137,0[67x25,137,0,2,67x24,137,26,3]}

Save it. Later:

<prefix> :select-layout b25d,204x50,0,0...

Your layout comes back. This is how tmux-resurrect saves panes (chapter 10).

Breaking and Joining Panes

Take a pane out of its window and make it a new window:

<prefix> !                   break pane into a new window

Take an existing window and make it a pane in the current window:

<prefix> :join-pane -s 3     join window 3 as a pane here (horizontal split)
<prefix> :join-pane -s 3 -h  vertical split

-s 3 means "source is window index 3 in the current session". Useful when you had two windows open and realise they should be side by side.

A Realistic Layout

You're working on an API. You want:

Editor on the left, full height
A shell on the top right for running commands
A log tail on the bottom right

Starting from a fresh window:

<prefix> %                   split vertically. Editor on left, blank shell on right
vim src/main.go              in the left pane
<prefix> Right               focus the right pane
<prefix> "                   split horizontally. Two right panes stacked
<prefix> Down                focus the bottom right
tail -f /tmp/api.log         in the bottom right
<prefix> Up                  focus the top right
# that shell is your command runner now

That layout is so common it's worth scripting (chapter 9). You'll end up with a shell function or tmuxp config that creates the whole thing with one command.

Synchronised Panes

<prefix> :setw synchronize-panes on

Now every keystroke you type goes to every pane in the current window. Useful for running the same command on a dozen servers over SSH at once. Dangerous if you forget it's on:

<prefix> :setw synchronize-panes off

Most people bind a toggle:

bind S setw synchronize-panes

The Pane Identity

Each pane has an index within its window, starting at 0 (or 1 with pane-base-index 1). Show indices with <prefix> q (the flash-and-jump key).

Target a specific pane:

work:0.1                      session work, window 0, pane 1

Common Pitfalls

"I lost a pane." Zoom is on. Press <prefix> z to unzoom. Or <prefix> w to see the full tree.

"Splits look wrong after resize." After resizing the terminal, tmux keeps pane sizes static. Cycle through layouts with <prefix> Space to reset, or set a specific layout like <prefix> M-4.

"I split, then couldn't find the divider." Status-bar themes sometimes make pane borders hard to see. Set pane border colours explicitly:

set -g pane-border-style fg=colour240
set -g pane-active-border-style fg=colour208

"<prefix> z only zooms one level." Correct. Zoom is binary: zoomed or not. To move into another pane while zoomed, you'd have to unzoom. A few plugins add nested zoom; usually the simple version is enough.

"Synchronised panes scared me." It should. Only turn it on when you want it, turn it off as soon as you're done. Bind a clear toggle and watch the status line.

Next Steps

Continue to 05-copy-mode.md to learn how to scroll, search, and yank text from any pane.