Documentation · tmux 3.7 · Panes

tmux Floating Panes
Guide for tmux 3.7+

Q: How do I create a floating pane in tmux?

Press Prefix then * (Ctrl+b * by default) 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%. A command can be added at the end, for example tmux new-pane htop.

Q: How do I move or resize a floating pane?

With set -g mouse on, drag the top border to move the pane, and drag the other borders or corners to resize it. In tmux 3.7 the keyboard cannot move or resize floating panes reliably, so the mouse is the supported method.

Q: Can I split, swap or tile a floating pane?

Not in tmux 3.7. split-window refuses to split a floating pane and swap-pane reports cannot swap floating panes. break-pane works and turns the pane into an ordinary tiled pane in its own window.

Floating panes are real tmux panes that sit on top of your tiled layout. This guide shows how to create, size, move and script them, how they differ from popups, and what they cannot do yet. Everything here was run against tmux 3.7c built from the official source.

TL;DR Overview

Floating panes in one minute:

Requires tmux 3.7 or later. Check with tmux -V; older versions answer unknown command: new-pane.
Create one with Prefix * or tmux new-pane. Size it with -x/-y, place it with -X/-Y.
With set -g mouse on, drag the top border to move it and the other borders or corners to resize it.
Unlike a popup, a floating pane is not modal, keeps running in the background and appears in list-panes.
It is an early feature: you cannot split or swap floating panes, and the keyboard cannot move or resize them.

Create Your First Floating Pane

Three ways to open one. All of them work in tmux 3.7 and later.

bash (tmux 3.7+)

# 1. The default key binding: 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

# Print the new pane's id and geometry (handy in scripts)

$ tmux new-pane -P -F "#{pane_id} #{pane_width}x#{pane_height} at #{pane_left},#{pane_top}"

Default size and position

With no options a floating pane is half the window width and a quarter of its height. Each new one is offset by 4 columns and 2 rows from the previous one, so a stack of panes cascades instead of hiding each other. If the window is zoomed, tmux unzooms it first.

It is a real pane

It has its own shell, scrollback, copy mode and pane ID. #{pane_floating_flag} is 1 for floating panes, and kill-pane, select-pane, capture-pane and send-keys work on it like on any other pane.

new-pane Options Reference

These flags are not described in the tmux 3.7c manual page yet. The list below comes from tmux list-commands and was tested one flag at a time.

Flag	What it does
`-x` `-y`	Width and height, in cells or as a percentage (`-x 80%`). Defaults: 50% wide, 25% high. A size of 100% is rejected as too large; use 99% or a cell count.
`-X` `-Y`	Left and top position, in cells or as a percentage of the window. If omitted, panes cascade from column 4, row 2.
`-c dir`	Start directory. Use `"#{pane_current_path}"` to open in the directory of the pane you are in.
`-e VAR=value`	Set an environment variable for the new pane. Can be repeated.
`-d`	Create the pane without making it active (keeps keyboard focus where it is).
`-P` `-F format`	Print information about the new pane, like `split-window -P`.
`-s` `-S` `-R`	Pane style, active border style and inactive border style, e.g. `-S "fg=cyan"`.
`-L`	Creates an ordinary tiled pane instead of a floating one. The implementation of `new-pane` is shared with `split-window`, which is why the other split flags (`-h`, `-v`, `-b`, `-l`, `-p`) are accepted but do not position a floating pane.
`shell-command`	Command to run instead of your shell. The pane closes when it exits unless `remain-on-exit` is on.

Moving and Resizing with the Mouse

In tmux 3.7 the mouse is the only supported way to move or resize a floating pane.

~/.tmux.conf

# Required for dragging floating pane borders

set -g mouse on

Move

Drag the top border of the floating pane. It follows the pointer.

Resize

Drag the left, right or bottom border to change one dimension, or any corner to change both.

Focus

Click inside a floating pane or on its border to make it active. Use select-pane -t %N from the keyboard.

Because the keyboard cannot reposition panes yet, choose the size and position when you create the pane (-x -y -X -Y) and bind that command to a key, as in the recipes below.

Practical Key Bindings

Add these to ~/.tmux.conf. Each one was loaded into tmux 3.7c and its commands were run to confirm the result.

~/.tmux.conf

# Prefix f: centred floating shell (80% x 70%) in the current directory

bind-key -N "Floating shell" f new-pane -c "#{pane_current_path}" -x 80% -y 70% -X 10% -Y 15% -S "fg=cyan"

# Prefix g: lazygit in a large floating pane (closes when you quit lazygit)

bind-key -N "Floating lazygit" g new-pane -c "#{pane_current_path}" -x 90% -y 90% -X 5% -Y 5% lazygit

# Prefix F: close the current pane only if it is floating

bind-key -N "Close floating pane" F if-shell -F "#{pane_floating_flag}" "kill-pane" "display-message 'Not a floating pane'"

# Prefix C-f: close every floating pane in the window

bind-key -N "Close all floating panes" C-f run-shell 'tmux list-panes -F "##{pane_id}" -f "##{pane_floating_flag}" | xargs -r -n1 tmux kill-pane -t'

Centring: a pane that is 80% wide starts 10% from the left, and one that is 70% high starts 15% from the top, so both margins are equal. List the bindings you have added with tmux list-keys -N.

Scratch terminal behaviour: tmux 3.7 has no way to hide a floating pane and bring it back, so a floating shell is closed rather than toggled. Run a long-lived task in a normal window and use the floating pane for short jobs such as git, a file picker or htop.

Scripting Floating Panes

Useful commands and formats for scripts and status lines.

bash

# Is the current pane floating? (prints 1 or 0)

$ tmux display-message -p "#{pane_floating_flag}"

# List only the floating panes of a window

$ tmux list-panes -f "#{pane_floating_flag}" -F "#{pane_id} #{pane_width}x#{pane_height}"

# Show a second status line that lists the panes

$ tmux set -g status 2

# Turn a floating pane into a normal pane in its own window

$ tmux break-pane -s %3

# Only bind the keys when this tmux knows new-pane (safe for shared dotfiles)

$ tmux if-shell "tmux list-commands | grep -q '^new-pane'" "bind f new-pane"

The version guard matters when one ~/.tmux.conf is shared between machines: on tmux 3.6 or earlier an unconditional bind f new-pane fails when the config loads, and the error message appears each time tmux starts. See the config reference for more conditional config patterns.

Floating Pane vs display-popup

Both draw a box over your layout. They are different tools.

	Floating pane	display-popup
Modal	No. You can switch to other panes while it is open.	Yes. It captures input until you close it.
Part of the window	Yes: a real pane with a pane ID, in `list-panes`.	No. It belongs to the client, not the window.
Survives detach	Yes, like any pane.	No. The popup is tied to the attached client.
Needs tmux	3.7 or later	3.2 or later
Convert to pane	See limits below: floating to tiled with `break-pane`	Popup menu can change it into a pane
Move / resize	Mouse only (3.7)	Set with `-x -y -w -h`; can be moved and resized with the mouse
Best for	Side tasks you want to keep visible while you work	One-shot tools: fzf pickers, menus, quick commands

Keep using display-popup for quick selectors such as fzf: it closes itself with -E and does not clutter the layout. Its flags are in the official tmux manual; the commands reference covers the other pane commands.

Current Limits in tmux 3.7

The release notes call this an early feature. These behaviours were confirmed on tmux 3.7c.

Action	Status	Detail
Split a floating pane	Not possible	`split-window` prints an error that it can't split a floating pane. Select a tiled pane first.
Swap with another pane	Not possible	`swap-pane` prints `cannot swap floating panes`.
Move or resize from the keyboard	Not supported	The release notes list `resize-pane` support as missing. Use the mouse or choose geometry at creation.
Convert tiled ↔ floating	Not supported	`break-pane` turns a floating pane into a tiled pane in a new window, but there is no command that floats an existing pane.
Saved layouts	Not restored	Restoring custom layouts that contain floating panes is not available yet; `#{window_layout}` does record them.

These limits are upstream's, not this site's. Watch the official CHANGES file for improvements and tell us if a later release changes something described here.

Troubleshooting

The three problems people hit first.

`unknown command: new-pane`

Your tmux is 3.6 or older. Run tmux -V. Upgrade with the macOS, Ubuntu/Linux or Windows (WSL) guide. Remember that a running server keeps its old version until you restart it.

The border will not drag

Make sure set -g mouse on is active (tmux show -g mouse) and that your terminal passes mouse events through. Drag exactly on the border line, and use the top border to move.

The pane vanished immediately

A pane running a command closes when the command exits. Add set -g remain-on-exit on while debugging, or run a shell and start the command inside it. See Troubleshooting.

Frequently Asked Questions

Quick answers about tmux floating panes.

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, and a floating pane supports the same escape sequences as any other pane. You create one with the new-pane command, bound to Prefix * by default.

How do I create a floating pane in tmux?

Press Prefix then * (Ctrl+b * by default) 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%. A command can be added at the end, for example tmux new-pane htop.

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 to check the version, then upgrade tmux or build 3.7 or later from source.

How do I move or resize a floating pane?

With set -g mouse on, drag the top border to move the pane, and drag the other borders or corners to resize it. In tmux 3.7 the keyboard cannot move or resize floating panes reliably, so the mouse is the supported method.

Can I split, swap or tile a floating pane?

Not in tmux 3.7. split-window refuses to split a floating pane and swap-pane reports cannot swap floating panes. break-pane works and turns the pane into an ordinary tiled pane in its own window.

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

A popup is modal: it takes over your keyboard until it is closed and is not part of the window layout. A floating pane is a real pane in the window. It stays open while you work in other panes, shows up in list-panes and the pane status line, and has its own scrollback.

Explore Related Documentation

Where floating panes fit in the rest of tmux.