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.
On this page
- Create your first floating pane
- Tiled, floating, modal or popup?
- new-pane options reference
- Move and resize from the keyboard (tmux 3.8)
- Move and resize with the mouse
- Float, tile, swap and split
- Modal panes (tmux 3.8)
- Practical key bindings
- Script floating panes
- Floating pane vs display-popup
- Limits and version differences
- Troubleshooting
- 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:
exitin it, or Ctrl+b x like any pane. - Error
unknown command: new-pane: your tmux is older than 3.7. Check withtmux -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.
# 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
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}'"'"'' EnterDefault 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_flagis 0 - Survives detach
- Yes
Floating pane 3.7+
- Create
new-paneor 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_flagis 1, flagF - 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,-Cor-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_flagis 1, flagsF A O - Survives detach
- Yes
Popup 3.2+
- Create
display-popup(aliaspopup)- 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
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.
| Flag | What it does |
|---|---|
-x -y | Width and height in cells or as a percentage (-x 80%), including the border. Default: half the width, a quarter of the height. |
-X -Y | Position of the top-left corner, in cells or percent. If omitted, panes cascade from the top left. |
-T title 3.8 | Pane title, shown by pane-border-status and #{pane_title}. split-window -T works too. |
-B lines 3.8 | Border characters for this pane: single, double, heavy, simple, number, spaces or none (no border, floating panes only). |
-O 3.8 | Make it a modal pane: it keeps the focus and blocks the other panes until it closes. |
-D -C -K 3.8 | With -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.8 | Keep the pane visible above a zoomed pane. Modal panes do this by default. |
-W 3.8 | Wait 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 msg | Keep 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=val | Start directory ("#{pane_current_path}" for the current one) and environment variables (repeatable). |
-d | Create it without moving the focus to it. |
-P -F fmt | Print information about the new pane, by default session:window.pane; -F '#{pane_id}' is best for scripts. |
-s -S -R | Pane style, active border style and inactive border style, for example -S fg=cyan. |
-M | Size the new pane by following a mouse drag; only useful in a mouse binding (it is what Ctrl+drag runs). |
-L | Create an ordinary tiled pane instead, exactly like split-window. |
shell-command | Run 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.
| Keys | Result | Command it runs |
|---|---|---|
| Ctrl+b g 1 … 4 | Move to the top-left, top-right, bottom-left or bottom-right corner | move-pane -P top-left … |
| Ctrl+b g ↑ and other arrows | Move to the middle of that edge | move-pane -P top-centre … |
| Ctrl+b g Alt+1 … M-4 | Resize to a quarter of the window and move to that corner | resize-pane -x 50% -y 50%, then move-pane |
| Ctrl+b g Alt+↑ and other arrows | Resize to half the window against that edge | resize-pane -x 100% -y 50% … |
| Ctrl+b g 0 | Fill the whole window | resize-pane -x 100% -y 100%, then move-pane -P top-left |
| Ctrl+b g , / . | A menu of move or move-and-resize positions | display-menu |
| Ctrl+b Alt+↓ / M-Right | Grow by 5 cells (bottom or right border) | resize-pane -D 5 |
| Ctrl+b Alt+↑ / M-Left | Shrink by 5 cells (bottom or right border) | resize-pane -D -5 |
| Ctrl+b Ctrl+↑ and other arrows | The same in steps of 1 cell | resize-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.
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 frontThe 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.

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}'"'"'' EnterMove 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.
set -g mouse on| Mouse action | What happens | Since |
|---|---|---|
| Drag the top border | Moves the pane | 3.7 |
| Drag another border or a corner | Resizes it in one or both directions | 3.7 |
| Alt + drag inside the pane | Moves it from anywhere, not just the border (move-pane -M) | 3.8 |
| Ctrl + drag anywhere | Draws a new floating pane the size of the drag (new-pane -M) | 3.8 |
| Click a pane or its border | Makes it the active pane (in 3.8 this also brings it to the front) | 3.7 |
Click [t] [z] [x] on the border line | Tile (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 pane | The pane menu, with Move, Move & Resize and Tile entries | 3.8 |
# Show a title bar with the [t][z][x] buttons on floating panes only (3.8)
set -g pane-border-status top-floatingbottom-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:
# 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 itjoin-paneon 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 -Wrefuses 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.
Modal panes (tmux 3.8)
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.
# 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 1Without -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.

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 TabYou 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:
# 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.
# 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"
%endifEvery 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.
# 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 %3Hooks 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 pane | Modal pane | display-popup | |
|---|---|---|---|
| Needs tmux | 3.7+ | 3.8+ | 3.2+ |
| Blocks other panes | No | Yes, in its window | Yes, for that client |
Has a pane id, in list-panes | Yes | Yes | No |
| Survives detach | Yes | Yes | No, it closes |
| Seen by other clients | Yes | Yes | No |
Targetable by send-keys, capture-pane | Yes | Yes | No |
| Move and resize | Keyboard (3.8) and mouse | Keyboard and mouse | Mouse: drag the border, right-drag to resize, Alt+drag |
| Closes when the command exits | Yes, unless -k | Yes, or -D/-C | With -E; otherwise Esc or Ctrl+c |
| Best for | Side tasks you keep while you work | Pickers and UIs that need your full attention | One-shot tools: fzf pickers, menus, a quick command |
# 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
| Feature | 3.6 and older | 3.7 | 3.8 |
|---|---|---|---|
Create (new-pane, Ctrl+b *) | No | Yes | Yes, plus Ctrl+drag |
| Move and resize | – | Mouse only | Keyboard, commands and mouse |
| Float or tile an existing pane | – | Floating to its own window with break-pane only | Ctrl+b @, break-pane -W, join-pane |
| Swap, split | – | Errors | Yes |
Modal panes, -T, -B, -W, -A | – | No | Yes |
| Restore in a layout string | – | No | Yes (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 reportpane_floating_flag0. Unzoom and they are back. - No clamping to the window.
move-pane -L 100can push a pane off screen. Ctrl+b g 0 ormove-pane -P centrebrings it back. - Preset layouts ignore floating panes. Ctrl+b Space and
select-layout tiledrearrange 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.