Floating Panes

Note

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

tmux 3.7 introduced floating panes — panes that sit above the tiled layout like a popup, but unlike a popup are not modal and behave like ordinary panes (full escape-sequence support, capture, send-keys, and so on). libtmux exposes them through Window.new_pane() and Pane.new_pane(), which wrap tmux’s new-pane command.

Creating a floating pane

Window.new_pane() returns the new Pane, just like Window.split(). The returned pane reports pane_floating_flag == "1":

>>> 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

width and height set the pane’s size (tmux’s -x / -y); x and y set its position in cells from the top-left of the window (tmux’s -X / -Y). The placement is reported back by 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

Floating panes accept the same overlay styling as tmux’s new-pane: style (the pane body), active_border_style, and inactive_border_style. Each takes a tmux style string, e.g. style="bg=black" or active_border_style="fg=green".

Keeping a pane open

By default a floating pane closes when its command exits. Pass keep=True to hold it open until a key is pressed (tmux’s -k), or message="..." to hold it open showing a custom remain-on-exit-format line (tmux’s -m); both set the pane’s remain-on-exit option to key:

>>> 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

Every pane carries the tmux 3.7 pane_floating_flag field, so floating panes can be told apart from tiled panes anywhere a Pane is available — including filtering a window’s panes:

>>> 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).