Floating panes

You can create floating panes — non-modal panes that hover above the tiled layout like a popup, but with full escape-sequence support and all the regular pane operations (capture, send-keys, and so on). You create them with Window.new_pane() or Pane.new_pane(), the same way you reach for Window.split() to add a tiled pane.

Most workflows never need one — tiled panes cover the everyday cases, and you can stop reading here unless you want a transient overlay (a quick log tail, a scratch shell, a status readout) sitting on top of your layout without rearranging it. Because a floating pane behaves like any other Pane, everything you already do — capturing output, sending keys, querying state — works on it unchanged.

Note

Floating panes require tmux 3.7+ (Window.new_pane() / Pane.new_pane() raise LibTmuxException on older tmux).

Creating a floating pane

When you call Window.new_pane(), you get back the new Pane, exactly as Window.split() hands you a tiled one. You can confirm a pane is floating by reading its pane_floating_flag, which is "1" when it floats:

>>> from libtmux.common import has_gte_version

>>> if has_gte_version("3.7"):
...     floating = window.new_pane(width=20, height=5, shell="sleep 30")
...     is_floating = floating.pane_floating_flag
... else:
...     is_floating = "1"
>>> is_floating
'1'

Sizing and positioning

You set the pane’s size with width and height (tmux’s -x / -y), and its position with x and y — cells measured from the top-left of the window (tmux’s -X / -Y). tmux reports the placement back through the pane_x / pane_y fields:

>>> from libtmux.common import has_gte_version

>>> if has_gte_version("3.7"):
...     placed = window.new_pane(width=20, height=5, x=2, y=1, shell="sleep 30")
...     position = (placed.pane_x, placed.pane_y)
... else:
...     position = ("2", "1")
>>> position
('2', '1')

Styling

For the rarer cases where appearance matters, you can style a floating pane with the same overlay options tmux’s new-pane accepts: style (the pane body), active_border_style, and inactive_border_style. Each takes a tmux style string, for example style="bg=black" or active_border_style="fg=green". The defaults read fine on most terminals, so reach for these only when you want a float to stand out.

Keeping a pane open

By default a floating pane closes the moment its command exits — fine for a fire-and-forget command, but you lose whatever it printed. When you want the output to linger, pass keep=True to hold the pane open until you press a key (tmux’s -k), or message="..." to hold it open showing a custom remain-on-exit-format line (tmux’s -m). The cost is explicit and small: both flip the pane’s remain-on-exit option to key, which buys you a pane that stays on screen and waits for you after the command finishes instead of vanishing:

>>> from libtmux.common import has_gte_version

>>> if has_gte_version("3.7"):
...     held = window.new_pane(width=20, height=5, shell="sleep 30", keep=True)
...     remain = held.cmd("show-options", "-p", "-v", "remain-on-exit").stdout
... else:
...     remain = ["key"]
>>> remain
['key']

Identifying floating panes

When you need to tell floating panes from tiled ones in code, reach for the tmux 3.7 pane_floating_flag field. Every Pane carries it, so you can branch on it anywhere you hold a pane — including filtering a window’s panes down to just the floats:

>>> from libtmux.common import has_gte_version

>>> if has_gte_version("3.7"):
...     _ = window.new_pane(width=20, height=5, shell="sleep 30")
...     floating = [p for p in window.panes if p.pane_floating_flag == "1"]
...     found = len(floating) >= 1
... else:
...     found = True
>>> found
True

See Pane.new_pane() for the full parameter reference and Format-token fields for the floating-pane geometry fields (pane_x, pane_y, pane_z, pane_floating_flag).