[tmux.app]
tmux 3.8

Docs · Panes · tmux 3.7+

tmux floating panes: new-pane, modal panes and the 3.8 move keys

A floating pane is a real tmux pane that sits on top of your split layout instead of taking space in it. Press Ctrl+b * or run tmux new-pane to open one (tmux 3.7 or later). In tmux 3.8 you can also move and resize it from the keyboard with Ctrl+b g, turn any pane into a floating one and back with Ctrl+b @, and make modal panes with new-pane -O.

Updated Tested on tmux 3.812 min read

On this page
  1. Create your first floating pane
  2. Tiled, floating, modal or popup?
  3. new-pane options reference
  4. Move and resize from the keyboard (tmux 3.8)
  5. Move and resize with the mouse
  6. Float, tile, swap and split
  7. Modal panes (tmux 3.8)
  8. Practical key bindings
  9. Script floating panes
  10. Floating pane vs display-popup
  11. Limits and version differences
  12. Troubleshooting
  13. Frequently asked questions

Quick answer

How do I use floating panes in tmux?

  • Create: Ctrl+b *, tmux new-pane, or hold Ctrl and drag with the mouse (3.8).
  • Size and place: tmux new-pane -x 80% -y 70% -X 10% -Y 15%.
  • Move: Ctrl+b g then 1–4 for corners or an arrow for an edge (3.8); or drag the top border.
  • Float or tile the current pane: Ctrl+b @ (3.8).
  • Close: exit in it, or Ctrl+b x like any pane.
  • Error unknown command: new-pane: your tmux is older than 3.7. Check with tmux -V.

Create your first floating pane

There are four ways to open one. All of them work on tmux 3.7 and later except the Ctrl+drag, which is new in 3.8.

shell (tmux 3.7+)
# 1. The default key: prefix then *  (Ctrl+b * unless you changed the prefix)
# 2. From inside tmux or from a script:
tmux new-pane
# 3. With a command; the pane closes when the command exits:
tmux new-pane htop
# 4. With a title, a size and a position, printing the new pane's id:
tmux new-pane -T scratch -x 60 -y 14 -X 25 -Y 6 -P -F '#{pane_id}'
%2
Real screenshot · tmux 3.8A floating pane titled scratch above two tiled panes on tmux 3.8. list-panes reports it with floating=1.
A floating pane titled scratch above two tiled panes on tmux 3.8. list-panes reports it with floating=1.
How this was captured

Captured 2026-10-28 17:54 UTC from a real xterm window running tmux 3.8 on Ubuntu 24.04. Nothing is mocked up. The commands that set up the screen:

tmux new-session -d -s work -n editor -x 110 -y 29
tmux split-window -h -t work:editor
tmux send-keys -t work:editor.0 'clear; seq 1 40 | paste -sd'"'"' '"'"' | fold -w 50' Enter
tmux send-keys -t work:editor.1 'clear; tmux -V' Enter
tmux new-pane -t work:editor -T scratch -x 60 -y 14 -X 25 -Y 6
tmux send-keys -t work:editor 'clear; tmux list-panes -F '"'"'#{pane_index} floating=#{pane_floating_flag} #{pane_width}x#{pane_height}'"'"'' Enter

Default size and position

With no options, a floating pane is half the window wide and a quarter of its height. Each new one cascades 4 columns right and 2 rows down from the last, so a stack of them never hides completely. If the window is zoomed, new-pane unzooms it first.

Sizes you give with -x and -y include the border, so -x 60 -y 14 gives 58 by 12 cells of content, as in the screenshot. Percentages are of the window: -x 100% -y 100% -X 0 -Y 0 fills it exactly.

It is a real pane

A floating pane has its own shell, scrollback, copy mode, pane id and title. send-keys, capture-pane, select-pane, kill-pane and respawn-pane work on it, it survives detach like any other pane, and #{pane_floating_flag} is 1. That is the main difference from a popup, which belongs to one client and disappears when that client detaches.

Tiled, floating, modal or popup?

tmux 3.8 has four kinds of boxes that can hold a program. Pick one in the explorer to see where it lives, and use the move pad to try the 3.8 Ctrl+b g keys on a floating pane.

Tiled pane

Create
split-window, Ctrl+b % or Ctrl+b "
Takes space
Yes: the other panes shrink to make room
Keyboard focus
Any pane, move with Ctrl+b ←
In list-panes
Yes, pane_floating_flag is 0
Survives detach
Yes

Floating pane 3.7+

Create
new-pane or Ctrl+b *, or Ctrl+drag (3.8)
Takes space
No: it sits above the tiled panes
Keyboard focus
Any pane: the ones underneath still work
In list-panes
Yes, pane_floating_flag is 1, flag F
Survives detach
Yes

Try the 3.8 move keys: Ctrl+b g then

new-pane

Modal pane 3.8

Create
new-pane -O (add -D, -C or -K)
Takes space
No: it floats, and stays above a zoomed pane
Keyboard focus
Only this pane until it closes; one per window
In list-panes
Yes, pane_modal_flag is 1, flags F A O
Survives detach
Yes

Popup 3.2+

Create
display-popup (alias popup)
Takes space
No: drawn over the whole client
Keyboard focus
Only the popup until it closes
In list-panes
No: it belongs to one client, not the window
Survives detach
No: it closes when that client detaches
Pick a pane type to see where it lives and what it does. The facts were checked on tmux 3.8; the move pad mirrors the default prefix g key table.

new-pane options reference

new-pane (alias newp) shares its code with split-window, so most split flags work too. These are the ones that matter for floating panes. Each one was run on tmux 3.8; flags marked 3.8 do not exist in 3.7.

FlagWhat it does
-x -yWidth and height in cells or as a percentage (-x 80%), including the border. Default: half the width, a quarter of the height.
-X -YPosition of the top-left corner, in cells or percent. If omitted, panes cascade from the top left.
-T title 3.8Pane title, shown by pane-border-status and #{pane_title}. split-window -T works too.
-B lines 3.8Border characters for this pane: single, double, heavy, simple, number, spaces or none (no border, floating panes only).
-O 3.8Make it a modal pane: it keeps the focus and blocks the other panes until it closes.
-D -C -K 3.8With -O: -D closes it on Esc or Ctrl+c, -C closes it on a click outside, -K sends every key to it, even the prefix.
-A 3.8Keep the pane visible above a zoomed pane. Modal panes do this by default.
-W 3.8Wait for the pane's command to exit and return its exit status: tmux new-pane -W 'vi notes.md' blocks the calling script.
-k -m msgKeep the pane open after the command exits until you press a key; -m sets the message shown.
-E -I-E creates an empty pane with no command (handy before a mode, see below). -I also forwards stdin into it: make 2>&1 | tmux new-pane -dI.
-c dir -e VAR=valStart directory ("#{pane_current_path}" for the current one) and environment variables (repeatable).
-dCreate it without moving the focus to it.
-P -F fmtPrint information about the new pane, by default session:window.pane; -F '#{pane_id}' is best for scripts.
-s -S -RPane style, active border style and inactive border style, for example -S fg=cyan.
-MSize the new pane by following a mouse drag; only useful in a mouse binding (it is what Ctrl+drag runs).
-LCreate an ordinary tiled pane instead, exactly like split-window.
shell-commandRun this instead of your shell. The pane closes when it exits, unless -k or remain-on-exit is set.

The full flag list for every command is in the commands reference, and the man page entry is explained in man tmux.

Move and resize from the keyboard (tmux 3.8)

Press Ctrl+b g to enter the move key table, then one key. The pane must be the active one and floating.

KeysResultCommand it runs
Ctrl+b g 1 … 4Move to the top-left, top-right, bottom-left or bottom-right cornermove-pane -P top-left …
Ctrl+b g ↑ and other arrowsMove to the middle of that edgemove-pane -P top-centre …
Ctrl+b g Alt+1 … M-4Resize to a quarter of the window and move to that cornerresize-pane -x 50% -y 50%, then move-pane
Ctrl+b g Alt+↑ and other arrowsResize to half the window against that edgeresize-pane -x 100% -y 50% …
Ctrl+b g 0Fill the whole windowresize-pane -x 100% -y 100%, then move-pane -P top-left
Ctrl+b g , / .A menu of move or move-and-resize positionsdisplay-menu
Ctrl+b Alt+↓ / M-RightGrow by 5 cells (bottom or right border)resize-pane -D 5
Ctrl+b Alt+↑ / M-LeftShrink by 5 cells (bottom or right border)resize-pane -D -5
Ctrl+b Ctrl+↑ and other arrowsThe same in steps of 1 cellresize-pane -D -1 …

The same commands work from the shell or a script. move-pane moves a floating pane when you give it -P, -X/-Y, -U/-D/-L/-R or -z; without those it behaves like join-pane. resize-pane on a floating pane moves the named border, and negative values shrink it.

shell (tmux 3.8)
tmux move-pane -P centre            # also top-left, bottom-centre, top-right-centre ...
tmux move-pane -X 10 -Y 5           # absolute position of the top-left corner
tmux move-pane -R 3                 # nudge 3 columns right (-D moves down 1)
tmux resize-pane -R 5               # right border 5 columns out
tmux resize-pane -U -2              # top border 2 rows in
tmux resize-pane -x 50% -y 40%      # absolute size, border included
tmux move-pane -P front             # stacking order: front, back, forward, backward
tmux move-pane -z 0                 # z-index 0 is the front

The 13 positions are top-left, top-centre, top-right, centre-left, centre, centre-right, bottom-left, bottom-centre, bottom-right and the quadrant centres top-left-centre, top-right-centre, bottom-left-centre, bottom-right-centre. The American spellings (center, top-center …) work too. Selecting a floating pane brings it to the front; #{pane_z} shows its place in the stack.

Real screenshot · tmux 3.8Two floating panes placed with move-pane -P top-left-centre and bottom-right, with pane-border-status top-floating. The list shows their pane flags (F = floating) and z-order.
Two floating panes placed with move-pane -P top-left-centre and bottom-right, with pane-border-status top-floating. The list shows their pane flags (F = floating) and z-order.
How this was captured

Captured 2026-10-29 00:50 UTC from a real xterm window running tmux 3.8 on Ubuntu 24.04. Nothing is mocked up. The commands that set up the screen:

# ~/.tmux.conf: set -g pane-border-status top-floating
tmux new-session -d -s work -n editor -x 110 -y 29
tmux split-window -h -t work:editor
tmux send-keys -t work:editor.0 'clear; tmux -V' Enter
tmux new-pane -t work:editor -T logs -x 50 -y 10
tmux move-pane -P bottom-right
tmux new-pane -t work:editor -T scratch -x 46 -y 9
tmux move-pane -P top-left-centre
tmux send-keys -t work:editor 'clear; tmux list-panes -F '"'"'#{pane_title} #{pane_flags} z=#{pane_z} @#{pane_left},#{pane_top}'"'"'' Enter

Move and resize with the mouse

The mouse is on by default in tmux 3.8. On 3.7 you need to turn it on first, and on 3.7 the mouse is the only way to move or resize a floating pane.

~/.tmux.conf (only needed before 3.8)
set -g mouse on
Mouse actionWhat happensSince
Drag the top borderMoves the pane3.7
Drag another border or a cornerResizes it in one or both directions3.7
Alt + drag inside the paneMoves it from anywhere, not just the border (move-pane -M)3.8
Ctrl + drag anywhereDraws a new floating pane the size of the drag (new-pane -M)3.8
Click a pane or its borderMakes it the active pane (in 3.8 this also brings it to the front)3.7
Click [t] [z] [x] on the border lineTile (or [f] float), zoom, or kill the pane. Shown when pane-border-status is on and the mouse is on.3.8
Right-click a floating paneThe pane menu, with Move, Move & Resize and Tile entries3.8
~/.tmux.conf
# Show a title bar with the [t][z][x] buttons on floating panes only (3.8)
set -g pane-border-status top-floating

bottom-floating puts the bar at the bottom; top and bottom show it on every pane.

Float, tile, swap and split

tmux 3.7 could only create floating panes. In 3.8 any pane can change between tiled and floating:

shell (tmux 3.8)
# prefix @ toggles the current pane: float a tiled pane, or tile a floating one
tmux break-pane -W                       # float the current pane (half width, quarter height)
tmux break-pane -W -s %1 -x 50% -y 50% -X 25% -Y 25%
tmux join-pane                           # put a floating pane back where it was
tmux swap-pane -s %1 -t %2               # swap a floating and a tiled pane
tmux split-window -h -t %2               # in a floating pane: a new floating pane beside it
  • join-pane on a floating pane with no target returns it to its previous place in the layout. Float it again and tmux restores its last floating size and position.
  • break-pane -W refuses a pane that is already floating (pane is already floating) and does not work in a zoomed window (can't float a pane while window is zoomed).
  • Splitting a floating pane creates a second floating pane of the same size next to it rather than splitting the box.
  • Layout strings in 3.8 are JSON and include floating panes, so select-layout "$(tmux display -p '#{window_layout}')" restores them. The preset layouts (tiled, even-horizontal …) arrange only the tiled panes.

Tiled panes have their own guide: split, resize, swap and move or join panes.

A modal pane is a floating pane that holds the focus. While it is open you cannot select or type into the other panes of that window; the window shows the flag O in the status line. A window can have only one (a second new-pane -O fails with window already has a modal pane), and it stays visible above a zoomed pane.

shell (tmux 3.8)
# A git UI that closes when you quit it; every key, even the prefix, goes to it
tmux new-pane -O -K -x 90% -y 90% -c "#{pane_current_path}" lazygit
# A modal shell you can dismiss with Esc or Ctrl+c, or by clicking outside it
tmux new-pane -O -D -C -x 70% -y 60%
# Which pane is modal?
tmux display -p '#{window_modal_pane} #{pane_modal_flag}'
%4 1

Without -K the prefix still works inside a modal pane, so Ctrl+b x closes it. Without -D, Esc and Ctrl+c go to the program as usual. tmux itself now uses a modal pane for the editor in buffer mode.

Modes and prompts inside floating panes

The 3.8 window switcher on Ctrl+b Tab is itself a floating pane: the default binding runs new-pane -E, moves it to the bottom center and starts switch-mode -k in it, so the pane closes when you pick a window.

Real screenshot · tmux 3.8prefix Tab on tmux 3.8: the fuzzy window switcher runs in a floating pane at the bottom of the window.
prefix Tab on tmux 3.8: the fuzzy window switcher runs in a floating pane at the bottom of the window.
How this was captured

Captured 2026-10-28 17:54 UTC from a real xterm window running tmux 3.8 on Ubuntu 24.04. Nothing is mocked up. The commands that set up the screen:

tmux new-session -d -s work -n editor -x 110 -y 29
tmux new-window -d -t work -n tests
tmux new-window -d -t work -n logs
tmux new-session -d -s api -n server
tmux send-keys -t work 'clear; echo '"'"'prefix Tab: the 3.8 window switcher'"'"'' Enter
(typed in the terminal) C-b Tab

You can do the same with other modes. -h hides the pane that runs the mode from the list and -k kills the pane when the mode exits; command-prompt -P opens a prompt inside the pane instead of on the status line:

~/.tmux.conf (tmux 3.8)
# prefix S: session tree in a centred floating pane that closes itself
bind S { new-pane -x 50% -y 50% -E ; move-pane -P centre ; choose-tree -hks }

Practical key bindings

Add these to ~/.tmux.conf and reload with tmux source ~/.tmux.conf. They use free keys; in 3.8 g is the move table and f is find-window, so do not reuse those unless you mean to. Each binding was loaded into tmux 3.8 and run.

~/.tmux.conf
# Floating panes need 3.7; skip these lines on older tmux (safe for shared dotfiles)
%if #{>=:#{version},3.8}

# prefix F: centred floating shell in the current directory, 80% x 70%
bind -N "Floating shell" F { new-pane -c "#{pane_current_path}" -x 80% -y 70% -T scratch ; move-pane -P centre }

# prefix G: lazygit as a modal pane (all keys go to it; it closes when you quit)
bind -N "Floating lazygit" G new-pane -O -K -c "#{pane_current_path}" -x 90% -y 90% -X 5% -Y 5% lazygit

# prefix K: close every floating pane in the window except the current one
bind -N "Close floating panes" K kill-pane -a -f "#{pane_floating_flag}"

# prefix B: run the build in a floating pane that stays open until a key
bind -N "Floating build" B new-pane -c "#{pane_current_path}" -x 70% -y 50% -m "build finished: press a key" "make"

# prefix j: a scratch session in a popup; prefix d inside it hides it again
bind -N "Scratch popup" j display-popup -E -w 80% -h 70% "tmux new -A -s scratch"

%endif

Every binding above was loaded into tmux 3.8 and pressed; the guard was checked on 3.4, where the block is skipped without errors.

Centring. move-pane -P centre does it for any size in 3.8. On 3.7, give a matching offset instead: a pane 80% wide starts at -X 10%, one 70% high at -Y 15%.

Version guard. A plain bind F new-pane in a config shared with an older machine fails there with unknown command: new-pane every time tmux starts. The %if line compares version strings, which is correct for every 3.x release. The block uses 3.8 because move-pane -P, -O and kill-pane -a -f are new in 3.8; use 3.7 for a block that only calls plain new-pane.

Scratch terminal. Floating panes cannot be hidden and brought back; closing one ends its shell. For a persistent toggle, use the popup binding on j above: it attaches to a session called scratch, and Ctrl+b d inside the popup detaches it, which closes the popup while the session keeps running. The tmux-floax plugin packages a similar idea.

Script floating panes

Formats and filters let a script or status line tell floating panes apart. The general scripting toolkit is in tmux scripting and API.

shell
# Is the current pane floating? Modal? (1 or 0)
tmux display -p '#{pane_floating_flag} #{pane_modal_flag}'
1 1
# Only the floating panes of a window, with their stacking order (0 = front)
tmux list-panes -f '#{pane_floating_flag}' -F '#{pane_id} #{pane_width}x#{pane_height} at #{pane_left},#{pane_top} z=#{pane_z}'
%2 38x8 at 61,21 z=1
%3 28x4 at 8,4 z=0
# Pane flags: * active, - last, F floating, A above zoom, O modal
tmux list-panes -F '#{pane_id} #{pane_flags}'
%0
%1
%2 -F
%3 *FAO
# Open a pane, run a command and wait for its exit status (3.8)
tmux new-pane -W -x 80% -y 60% 'pytest -q'; echo "tests exited with $?"
# Turn a floating pane into a normal pane in its own window
tmux break-pane -s %3

Hooks fire for floating panes like any other: pane-resized when you resize one, pane-created and pane-exited, and window-layout-changed. Zoom has its own window-zoomed and window-unzoomed hooks in 3.8.

Floating pane vs display-popup

Both draw a box over your layout. A popup is a temporary overlay that belongs to the client you are using; a floating pane is part of the window.

Floating paneModal panedisplay-popup
Needs tmux3.7+3.8+3.2+
Blocks other panesNoYes, in its windowYes, for that client
Has a pane id, in list-panesYesYesNo
Survives detachYesYesNo, it closes
Seen by other clientsYesYesNo
Targetable by send-keys, capture-paneYesYesNo
Move and resizeKeyboard (3.8) and mouseKeyboard and mouseMouse: drag the border, right-drag to resize, Alt+drag
Closes when the command exitsYes, unless -kYes, or -D/-CWith -E; otherwise Esc or Ctrl+c
Best forSide tasks you keep while you workPickers and UIs that need your full attentionOne-shot tools: fzf pickers, menus, a quick command
shell
# a popup that closes itself when fzf exits
tmux display-popup -E -w 80% -h 60% 'git branch | fzf | xargs git switch'
# the same as a floating pane that you can keep, move and come back to
tmux new-pane -x 80% -y 60% -X 10% -Y 20%

Limits and version differences

Feature3.6 and older3.73.8
Create (new-pane, Ctrl+b *)NoYesYes, plus Ctrl+drag
Move and resize–Mouse onlyKeyboard, commands and mouse
Float or tile an existing pane–Floating to its own window with break-pane onlyCtrl+b @, break-pane -W, join-pane
Swap, split–ErrorsYes
Modal panes, -T, -B, -W, -A–NoYes
Restore in a layout string–NoYes (JSON layouts)

What tmux 3.8 still does not do, checked on the 3.8 release:

  • No hide or minimize. A floating pane is open or closed. Use a popup attached to a scratch session for a toggle (see recipes).
  • Zoom hides ordinary floating panes. Zooming a tiled pane hides floating panes not created with -A, and while zoomed they report pane_floating_flag 0. Unzoom and they are back.
  • No clamping to the window. move-pane -L 100 can push a pane off screen. Ctrl+b g 0 or move-pane -P centre brings it back.
  • Preset layouts ignore floating panes. Ctrl+b Space and select-layout tiled rearrange only tiled panes.
  • Old distributions do not have them. Ubuntu 24.04 ships 3.4 and Debian 13 ships 3.5a. See which tmux each system ships and build 3.8 from source.

Troubleshooting

unknown command: new-pane

Your tmux is 3.6 or older. Run tmux -V and upgrade (macOS, Linux, Windows/WSL). A running server keeps its old version until you restart it: tmux kill-server, then start tmux again. If tmux -V already says 3.7 or 3.8, you are still attached to an older server; see troubleshooting.

prefix g or prefix @ does nothing

Those keys are new in 3.8. On 3.7, move floating panes with the mouse. If you are on 3.8, check that your config does not unbind them: tmux list-keys -T prefix g.

The border will not drag

Check tmux show -g mouse (it should say on; the default before 3.8 was off) and that your terminal passes mouse events through. Drag exactly on the border line, the top one to move. In 3.8 you can hold Alt and drag anywhere inside instead.

The pane vanished immediately

A pane that runs a command closes when the command exits. Use new-pane -k to keep it open until a key, or run a shell and start the command inside it.

My floating panes disappeared when I zoomed

That is expected: zoom hides floating panes created without -A. Press Ctrl+b z again.

Frequently asked questions

What are tmux floating panes?

Floating panes were added in tmux 3.7. They are real panes that sit on top of the tiled layout, like popups, but they are not modal: you can keep working in the panes underneath, they survive detach, and they support the same escape sequences as any other pane. You create one with the new-pane command, bound to prefix * by default. tmux 3.8 adds keyboard moving and resizing, modal panes, and converting between floating and tiled.

How do I create a floating pane in tmux?

Press Ctrl+b then *, or run tmux new-pane. Add -x and -y for the size and -X and -Y for the position, for example tmux new-pane -x 80% -y 70% -X 10% -Y 15%, and a command at the end to run it, such as tmux new-pane htop. In tmux 3.8 you can also hold Ctrl and drag with the mouse.

Why do I get "unknown command: new-pane"?

Your tmux is older than 3.7; floating panes do not exist in 3.6 or earlier. Run tmux -V, upgrade or build 3.8 from source, and restart the tmux server (tmux kill-server) so the new version runs.

How do I move or resize a floating pane?

In tmux 3.8 press prefix g then 1 to 4 for a corner, an arrow for an edge, or 0 to fill the window; prefix Alt+arrow resizes it by 5 cells. From a script use move-pane -P centre or move-pane -X 10 -Y 5 and resize-pane -x 50% -y 40%. With the mouse, drag the top border to move and the other borders or corners to resize. In tmux 3.7 only the mouse works.

Can I split, swap or tile a floating pane?

Yes, in tmux 3.8. prefix @ toggles the current pane between floating and tiled (break-pane -W and join-pane), swap-pane swaps floating and tiled panes, and split-window in a floating pane creates a second floating pane beside it. tmux 3.7 refuses to split or swap floating panes.

What is the difference between a floating pane and display-popup?

A popup is modal and belongs to one client: it takes over your keyboard until it closes, is not in list-panes, and disappears when you detach. A floating pane is a real pane in the window. It stays open while you work in other panes, other clients see it, it survives detach, and it has its own scrollback. tmux 3.8 modal panes (new-pane -O) sit in between: they block the window like a popup but are still real panes.

What is a modal pane in tmux?

A modal pane, new in tmux 3.8, is a floating pane created with new-pane -O that keeps the focus until it closes, so the other panes in the window cannot be used. Add -D to close it with Esc or Ctrl+c, -C to close it with a click outside, and -K to send every key, including the prefix, to it. A window can have one modal pane at a time.

Can I hide a floating pane and bring it back?

Not in tmux 3.8: closing a floating pane ends its program. For a scratch terminal you can toggle, bind a popup that attaches to its own session, for example bind j display-popup -E "tmux new -A -s scratch", or move the pane to another window with break-pane and back with join-pane.

Keep learning

Something wrong or out of date on this page? Email hello@tmux.app and we will fix it.