Panes¶

Contain pseudoterminals (pty(4))
Exist inside Windows
Identified by %, e.g. %313

class libtmux.Pane ¶ class[source] class[source] class libtmux.Pane ¶

Bases: Obj, OptionsMixin, HooksMixin

Pane instances can send commands directly to a pane, or traverse between linked tmux objects.

Examples

>>> pane
Pane(%1 Window(@1 1:..., Session($1 ...)))

>>> pane in window.panes
True

>>> pane.window
Window(@1 1:..., Session($1 ...))

>>> pane.session
Session($1 ...)

The pane can be used as a context manager to ensure proper cleanup:

>>> with window.split() as pane:
...     pane.send_keys('echo "Hello"')
...     # Do work with the pane
...     # Pane will be killed automatically when exiting the context

Notes

Changed in version 0.8: Renamed from .tmux to .cmd.

References

[pane_manual]

tmux pane. openbsd manpage for TMUX(1).: “Each window displayed by tmux may be split into one or more panes; each pane takes up a certain area of the display and is a separate terminal.”

https://man.openbsd.org/tmux.1#WINDOWS_AND_PANES. Accessed April 1st, 2018.

refresh() ¶ method[source] method[source] refresh() ¶

Refresh pane attributes from tmux.

Scoped to this pane’s own window (list-panes -t %ID), so tmux – not libtmux – decides which session the pane belongs to. See Pane.from_pane_id().

Raises:

ValueError – When pane_id is unset. Surfaces a clear error under python -O, where an assert would be stripped.
TmuxObjectDoesNotExist – When the pane no longer exists.
LibTmuxException – When tmux itself is unreachable.

Return type:

None

Examples

>>> pane.refresh()
>>> pane.pane_id
'%1'

from_pane_id(server, pane_id) ¶ classmethod method[source] classmethod method[source] from_pane_id(server, pane_id) ¶

Create Pane from existing pane_id.

tmux’s cmd_find routes a -t target by sigil, so a %-id handed to list-panes resolves to that pane’s window and lists it. Every row comes back stamped with the session tmux considers canonical for that window – the most recently active one – which is the same session display-message -t %ID '#{session_id}' reports. A window linked into several sessions therefore gets one authoritative answer instead of “whichever session sorted last”.

Parameters:

server (Server) – The tmux server holding the pane.
pane_id (str) – Pane id, e.g. "%3".

Return type:

Pane

Raises:

TmuxObjectDoesNotExist – When no such pane exists on a reachable server.
LibTmuxException – When tmux itself is unreachable.

Examples

>>> Pane.from_pane_id(server=pane.server, pane_id=pane.pane_id)
Pane(%1 Window(@1 1:..., Session($1 ...)))

from_env(env=None) ¶ classmethod method[source] classmethod method[source] from_env(env=None) ¶

Return the pane this process is running inside of.

Reads $TMUX for the server’s socket and $TMUX_PANE for the pane id, then asks tmux for the rest. The stale session id inside $TMUX is never consulted, so the answer stays correct after the pane’s window has been moved or linked elsewhere.

Parameters:

env (typing.Mapping, optional) – Environment to read. Defaults to os.environ, which is what a process running inside a pane wants; pass an explicit mapping to resolve on behalf of another pane.

Return type:

Pane

Raises:

NotInsideTmux – When $TMUX or $TMUX_PANE is unset or malformed.
TmuxObjectDoesNotExist – When the pane named by $TMUX_PANE is gone.
LibTmuxException – When the server named by $TMUX is unreachable.

Examples

>>> Pane.from_env(env)
Pane(%1 Window(@1 1:..., Session($1 ...)))

>>> Pane.from_env(env).pane_id == pane.pane_id
True

Outside a pane there is nothing to resolve:

>>> from libtmux import exc
>>> try:
...     Pane.from_env({})
... except exc.NotInsideTmux as e:
...     print(e)
Not inside a tmux pane: $TMUX is unset or empty

Added in version 0.62.

cmd(cmd, *args, target=None) ¶ method[source] method[source] cmd(cmd, *args, target=None) ¶

Execute tmux subcommand within pane context.

Automatically binds target by adding -t for object’s pane ID to the command. Pass target to keyword arguments to override.

Examples

>>> pane.cmd('split-window', '-P').stdout[0]
'libtmux...:...'

From raw output to an enriched Pane object:

>>> Pane.from_pane_id(pane_id=pane.cmd(
... 'split-window', '-P', '-F#{pane_id}').stdout[0], server=pane.server)
Pane(%... Window(@... ...:..., Session($1 libtmux_...)))

Parameters:

target (str, optional) – Optional custom target override. By default, the target is the pane ID.
cmd (str)
args (Any)

Return type:

server.cmd()

resize(adjustment_direction=None, adjustment=None, height=None, width=None, zoom=None, mouse=None, trim_below=None) ¶ method[source] method[source] resize(adjustment_direction=None, adjustment=None, height=None, width=None, zoom=None, mouse=None, trim_below=None) ¶

Resize tmux pane.

Parameters:

adjustment_direction (ResizeAdjustmentDirection, optional) – direction to adjust, Up, Down, Left, Right.
adjustment (ResizeAdjustmentDirection, optional)
height (int, optional) – resize-pane -y dimensions
width (int, optional) – resize-pane -x dimensions
zoom (bool) – expand pane
mouse (bool) – resize via mouse
trim_below (bool) – trim below cursor

Raises:

Return type:

Pane

Notes

Three types of resizing are available:

Adjustments: adjustment_direction and adjustment.
Manual resizing: height and / or width.
Zoom / Unzoom: zoom.

capture_pane(start: Literal['-'] | int | None = None, end: Literal['-'] | int | None = None, *, escape_sequences: bool = False, escape_non_printable: bool = False, join_wrapped: bool = False, preserve_trailing: bool = False, trim_trailing: bool = False, alternate_screen: bool = False, quiet: bool = False, mode_screen: bool = False, pending: bool = False, hyperlinks: bool = False, line_numbers: bool = False, line_flags: bool = False, to_buffer: str) → None ¶ method[source] method[source] capture_pane(start: Literal['-'] | int | None = None, end: Literal['-'] | int | None = None, *, escape_sequences: bool = False, escape_non_printable: bool = False, join_wrapped: bool = False, preserve_trailing: bool = False, trim_trailing: bool = False, alternate_screen: bool = False, quiet: bool = False, mode_screen: bool = False, pending: bool = False, hyperlinks: bool = False, line_numbers: bool = False, line_flags: bool = False, to_buffer: str) → None ¶

capture_pane(start: Literal['-'] | int | None = None, end: Literal['-'] | int | None = None, *, escape_sequences: bool = False, escape_non_printable: bool = False, join_wrapped: bool = False, preserve_trailing: bool = False, trim_trailing: bool = False, alternate_screen: bool = False, quiet: bool = False, mode_screen: bool = False, pending: bool = False, hyperlinks: bool = False, line_numbers: bool = False, line_flags: bool = False, to_buffer: None = None) → list[str] method method capture_pane(start: Literal['-'] | int | None = None, end: Literal['-'] | int | None = None, *, escape_sequences: bool = False, escape_non_printable: bool = False, join_wrapped: bool = False, preserve_trailing: bool = False, trim_trailing: bool = False, alternate_screen: bool = False, quiet: bool = False, mode_screen: bool = False, pending: bool = False, hyperlinks: bool = False, line_numbers: bool = False, line_flags: bool = False, to_buffer: None = None) → list[str]

Capture text from pane.

$ tmux capture-pane to pane. $ tmux capture-pane -S -10 to pane. $ tmux capture-pane -E 3 to pane. $ tmux capture-pane -S - -E - to pane.

Parameters:

start (str | int, optional) – Specify the starting line number. Zero is the first line of the visible pane. Positive numbers are lines in the visible pane. Negative numbers are lines in the history. - is the start of the history. Default: None
end (str | int, optional) – Specify the ending line number. Zero is the first line of the visible pane. Positive numbers are lines in the visible pane. Negative numbers are lines in the history. - is the end of the visible pane. Default: None
escape_sequences (bool, optional) – Include ANSI escape sequences for text and background attributes (-e flag). Useful for capturing colored output. Default: False
escape_non_printable (bool, optional) – Escape non-printable characters as octal \\xxx format (-C flag). Useful for binary-safe capture. Default: False
join_wrapped (bool, optional) – Join wrapped lines and preserve trailing spaces (-J flag). Lines that were wrapped by tmux will be joined back together. Default: False
preserve_trailing (bool, optional) – Preserve trailing spaces at each line’s end (-N flag). Default: False
trim_trailing (bool, optional) – Trim trailing positions with no characters (-T flag). Only includes characters up to the last used cell. Requires tmux 3.4+. If used with tmux < 3.4, a warning is issued and the flag is ignored. Default: False
alternate_screen (bool, optional) –
Capture from the alternate screen (-a flag). Default: False

Added in version 0.56.
quiet (bool, optional) –
Suppress errors silently (-q flag). Default: False

Added in version 0.56.
mode_screen (bool, optional) –
Capture from the mode screen (e.g. copy mode) instead of the pane (-M flag). Requires tmux 3.6+. Default: False

Added in version 0.56.
pending (bool, optional) –
Capture pending output — the bytes tmux has read from the pane but not yet committed to the terminal (-P flag). These are bytes that begin an incomplete escape sequence and are still pending the parser’s ground state (tmux’s input_pending() / since_ground buffer), distinct from the default capture (the pane’s screen history). Useful for diagnosing programs whose output stalls mid-sequence. Default: False

Added in version 0.57.
hyperlinks (bool, optional) – Capture only hyperlink targets in the selected lines (-H flag). Requires tmux 3.7+. If used with tmux < 3.7, a warning is issued and the flag is ignored. Default: False
line_numbers (bool, optional) – Prefix each captured line with its line number (-L flag). Requires tmux 3.7+. If used with tmux < 3.7, a warning is issued and the flag is ignored. Default: False
line_flags (bool, optional) – Prefix each captured line with its flags, e.g. H for a line with a hyperlink (-F flag). Requires tmux 3.7+. If used with tmux < 3.7, a warning is issued and the flag is ignored. Default: False
to_buffer (str, optional) –
Write the capture into the named tmux buffer (-b flag) instead of returning it. When set, -p is omitted and the wrapper returns None.

Added in version 0.56.

Returns:

Captured pane content, or None when to_buffer is set.

Return type:

list[str] or None

Examples

>>> pane = window.split(shell='sh')
>>> pane.capture_pane()
['$']

>>> pane.send_keys('echo "Hello world"', enter=True)

>>> pane.capture_pane()
['$ echo "Hello world"', 'Hello world', '$']

>>> print(chr(10).join(pane.capture_pane()))
$ echo "Hello world"
Hello world
$

send_keys(cmd=None, enter=True, suppress_history=False, literal=False, reset=None, copy_mode_cmd=None, repeat=None, expand_formats=None, hex_keys=None, target_client=None, key_name=None) ¶ method[source] method[source] send_keys(cmd=None, enter=True, suppress_history=False, literal=False, reset=None, copy_mode_cmd=None, repeat=None, expand_formats=None, hex_keys=None, target_client=None, key_name=None) ¶

$ tmux send-keys to the pane.

A leading space character is added to cmd to avoid polluting the user’s history.

When cmd is omitted (None), the wrapper emits a flag-only invocation — useful with reset=True or repeat=N to invoke tmux’s deliberate count == 0 branch in cmd-send-keys.c that runs the flag effect without sending any keys. In flag-only mode, enter is forced False (no keys → no Enter).

Parameters:

cmd (str | None, optional) –
Text or input into pane. None for flag-only invocation (requires reset, repeat, or copy_mode_cmd to be set).

Changed in version 0.57: Now optional. None triggers tmux’s flag-only path.
enter (bool, optional) – Send enter after sending the input, default True.
suppress_history (bool, optional) –
Prepend a space to command to suppress shell history, default False.

Changed in version 0.14: Default changed from True to False.
literal (bool, optional) – Send keys literally, default False.
reset (bool, optional) –
Reset terminal state before sending keys (-R flag).

Added in version 0.56.
copy_mode_cmd (str, optional) –
Send a command to copy mode instead of keys (-X flag). When set, cmd is ignored.

Added in version 0.56.
repeat (int, optional) –
Repeat count for the key (-N flag).

Added in version 0.56.
expand_formats (bool, optional) –
Expand tmux format strings in keys (-F flag).

Added in version 0.56.
hex_keys (bool, optional) –
Send keys as hex values (-H flag).

Added in version 0.56.
target_client (str, optional) –
Specify a target client (-c flag). Requires tmux 3.4+.

Added in version 0.56.
key_name (bool, optional) –
Handle keys as key names (-K flag). Requires tmux 3.4+.

Added in version 0.56.

Raises:

ValueError – If cmd is None and no flag-only path is selected (reset, repeat, or copy_mode_cmd).

Return type:

None

Examples

>>> pane = window.split(shell='sh')
>>> pane.capture_pane()
['$']

>>> pane.send_keys('echo "Hello world"', enter=True)

>>> pane.capture_pane()
['$ echo "Hello world"', 'Hello world', '$']

>>> print('\n'.join(pane.capture_pane()))
$ echo "Hello world"
Hello world
$

Flag-only invocation — reset terminal state without sending any keys:

>>> pane.send_keys(reset=True)

Display message to pane.

Displays a message in target-client status line. The get_text=False path renders in the status line and is not programmatically verifiable; only get_text=True returns output.

Parameters:

cmd (str) – Special parameters to request from pane.
get_text (bool, optional) – Returns only text without displaying a message in target-client status line.
format_string (str, optional) –
Format string for output (-F flag).

Added in version 0.56.
all_formats (bool, optional) –
List all format variables (-a flag).

Added in version 0.56.
verbose (bool, optional) –
Show format variable types (-v flag).

Added in version 0.56.
no_expand (bool, optional) –
Suppress format expansion; output is returned as a literal string (-l flag). Requires tmux 3.4+.

Added in version 0.56.
target_client (str, optional) –
Target client (-c flag).

Added in version 0.56.
delay (int, optional) –
Display time in milliseconds (-d flag).

Added in version 0.56.
notify (bool, optional) –
Do not wait for input (-N flag).

Added in version 0.56.
update_pane (bool, optional) –
Allow the pane to keep updating while the message is displayed (-C flag). By default tmux freezes the pane while a status message is shown. Requires tmux 3.6+ (introduced upstream by commit 80eb460f).

Added in version 0.56.

Returns:

Message output if get_text is True, otherwise None.

Return type:

list[str] | None

Notes

Stderr from tmux is reported via warnings.warn(), not raised. Callers that want to escalate to an exception can wrap the call in warnings.catch_warnings() with filterwarnings("error").

Changed in version 0.57: Reports stderr via warnings.warn() instead of raising.

kill(all_except=None) ¶ method[source] method[source] kill(all_except=None) ¶

Kill Pane.

$ tmux kill-pane.

Examples

Kill a pane:

>>> pane_1 = pane.split()

>>> pane_1 in window.panes
True

>>> pane_1.kill()

>>> pane_1 not in window.panes
True

Kill all panes except the current one:

>>> pane.window.resize(height=100, width=100)
Window(@1 1...)

>>> one_pane_to_rule_them_all = pane.split()

>>> other_panes = pane.split(
...     ), pane.split()

>>> all([p in window.panes for p in other_panes])
True

>>> one_pane_to_rule_them_all.kill(all_except=True)

>>> all([p not in window.panes for p in other_panes])
True

>>> one_pane_to_rule_them_all in window.panes
True

Parameters:: all_except (bool | None)
Return type:: None

select(*, direction=None, last=None, keep_zoom=None, mark=None, clear_mark=None, disable_input=None, enable_input=None) ¶ method[source] method[source] select(*, direction=None, last=None, keep_zoom=None, mark=None, clear_mark=None, disable_input=None, enable_input=None) ¶

Select pane.

Parameters:

direction (ResizeAdjustmentDirection, optional) –
Select the pane in the given direction (-U, -D, -L, -R).

Added in version 0.56.
last (bool, optional) –
Select the last (previously selected) pane (-l flag).

Added in version 0.56.
keep_zoom (bool, optional) –
Keep the window zoomed if it was zoomed (-Z flag).

Added in version 0.56.
mark (bool, optional) –
Set the marked pane (-m flag).

Added in version 0.56.
clear_mark (bool, optional) –
Clear the marked pane (-M flag).

Added in version 0.56.
disable_input (bool, optional) –
Disable input to the pane (-d flag).

Added in version 0.56.
enable_input (bool, optional) –
Enable input to the pane (-e flag).

Added in version 0.56.

Returns:

Self, for method chaining.

Return type:

Pane

Examples

>>> pane = window.active_pane
>>> new_pane = window.split()
>>> pane.refresh()
>>> active_panes = [p for p in window.panes if p.pane_active == '1']

>>> pane in active_panes
True
>>> new_pane in active_panes
False

>>> new_pane.pane_active == '1'
False

>>> new_pane.select()
Pane(...)

>>> new_pane.pane_active == '1'
True

split(target=None, start_directory=None, attach=False, direction=None, full_window_split=None, zoom=None, shell=None, size=None, percentage=None, environment=None, empty=None, style=None, active_border_style=None, inactive_border_style=None, message=None, keep=None) ¶ method[source] method[source] split(target=None, start_directory=None, attach=False, direction=None, full_window_split=None, zoom=None, shell=None, size=None, percentage=None, environment=None, empty=None, style=None, active_border_style=None, inactive_border_style=None, message=None, keep=None) ¶

Split window and return Pane, by default beneath current pane.

Parameters:

target (optional) – Optional, custom target-pane, used by Window.split().
attach (bool, optional) – make new window the current window after creating it, default True.
start_directory (str or PathLike, optional) – specifies the working directory in which the new window is created.
direction (PaneDirection, optional) – split in direction. If none is specified, assume down.
full_window_split (bool, optional) – split across full window width or height, rather than active pane.
zoom (bool, optional) – expand pane
shell (str, optional) –
execute a command on splitting the window. The pane will close when the command exits.

NOTE: When this command exits the pane will close. This feature is useful for long-running processes where the closing of the window upon completion is desired.
size (int, optional) – Cell/row count to occupy with respect to current window.
percentage (int, optional) –
Percentage (0-100) of the window to occupy (-p flag). Mutually exclusive with size.

Added in version 0.56.
environment (dict, optional) – Environmental variables for new pane. Passthrough to -e.
empty (bool, optional) – Create an empty pane with no command (-E flag) instead of spawning the default shell. Requires tmux 3.7+. If used with tmux < 3.7, a warning is issued and the flag is ignored.
style (str, optional) – Style for the new pane (-s). Requires tmux 3.7+.
active_border_style (str, optional) – Active-pane border style (-S). Requires tmux 3.7+.
inactive_border_style (str, optional) – Inactive-pane border style (-R). Requires tmux 3.7+.
message (str, optional) – Keep the pane open (until a key is pressed) after exit, showing this remain-on-exit-format message (-m). Requires tmux 3.7+.
keep (bool, optional) – Keep the pane open until a key is pressed after exit (-k). Requires tmux 3.7+. These 3.7 flags warn and are ignored below 3.7.

Return type:

Pane

Examples

>>> (pane.at_left, pane.at_right,
...  pane.at_top, pane.at_bottom)
(True, True,
True, True)

>>> new_pane = pane.split()

>>> (new_pane.at_left, new_pane.at_right,
...  new_pane.at_top, new_pane.at_bottom)
(True, True,
False, True)

>>> right_pane = pane.split(direction=PaneDirection.Right)

>>> (right_pane.at_left, right_pane.at_right,
...  right_pane.at_top, right_pane.at_bottom)
(False, True,
True, False)

>>> left_pane = pane.split(direction=PaneDirection.Left)

>>> (left_pane.at_left, left_pane.at_right,
...  left_pane.at_top, left_pane.at_bottom)
(True, False,
True, False)

>>> top_pane = pane.split(direction=PaneDirection.Above)

>>> (top_pane.at_left, top_pane.at_right,
...  top_pane.at_top, top_pane.at_bottom)
(False, False,
True, False)

>>> pane = session.new_window().active_pane

>>> top_pane = pane.split(direction=PaneDirection.Above, full_window_split=True)

>>> (top_pane.at_left, top_pane.at_right,
...  top_pane.at_top, top_pane.at_bottom)
(True, True,
True, False)

>>> bottom_pane = pane.split(
... direction=PaneDirection.Below,
... full_window_split=True)

>>> (bottom_pane.at_left, bottom_pane.at_right,
...  bottom_pane.at_top, bottom_pane.at_bottom)
(True, True,
False, True)

new_pane(target=None, start_directory=None, attach=False, shell=None, environment=None, width=None, height=None, x=None, y=None, zoom=None, empty=None, style=None, active_border_style=None, inactive_border_style=None, message=None, keep=None) ¶ method[source] method[source] new_pane(target=None, start_directory=None, attach=False, shell=None, environment=None, width=None, height=None, x=None, y=None, zoom=None, empty=None, style=None, active_border_style=None, inactive_border_style=None, message=None, keep=None) ¶

Create a floating Pane via $ tmux new-pane (tmux 3.7+).

Use split() for a tiled pane. Floating panes sit above the tiled layout like a popup, but unlike a popup they are not modal and behave like normal panes. The returned pane has pane_floating_flag == "1".

Parameters:

target (int or str, optional) – Custom target-pane, used by Window.new_pane().
start_directory (str or PathLike, optional) – Working directory for the new pane (-c flag).
attach (bool, optional) – Make the new pane the active pane, default False (-d when not attaching).
shell (str, optional) – Command to run in the pane. The pane closes when it exits.
environment (dict, optional) – Environment variables for the new pane (-e flag).
width (int, optional) – Width of the floating pane in cells (-x flag).
height (int, optional) – Height of the floating pane in cells (-y flag).
x (int, optional) – X position of the floating pane in cells (-X flag).
y (int, optional) – Y position of the floating pane in cells (-Y flag).
zoom (bool, optional) – Zoom the pane (-Z flag).
empty (bool, optional) – Create an empty pane with no command (-E flag).
style (str, optional) – Style for the floating pane (-s flag).
active_border_style (str, optional) – Border style when the pane is active (-S flag).
inactive_border_style (str, optional) – Border style when the pane is inactive (-R flag).
message (str, optional) – Keep the pane open (until a key is pressed) after the command exits, showing this remain-on-exit-format message (-m flag).
keep (bool, optional) – Keep the pane open until a key is pressed after the command exits (-k flag), using the default remain-on-exit-format.

Returns:

The newly created floating pane.

Return type:

Pane

Raises:

libtmux.exc.LibTmuxException – If the tmux server is older than 3.7 (new-pane is unavailable).

Examples

>>> from libtmux.common import has_gte_version
>>> if has_gte_version("3.7"):
...     floating = pane.new_pane(width=40, height=10, shell="sleep 5")
...     is_floating = floating.pane_floating_flag
... else:
...     is_floating = "1"
>>> is_floating
'1'

display_popup(command=None, *, close_on_exit=None, close_on_success=None, close_existing=None, target_client=None, width=None, height=None, x=None, y=None, start_directory=None, title=None, border_lines=None, style=None, border_style=None, environment=None, no_border=None, close_on_any_key=None, no_keys=None) ¶ method[source] method[source] display_popup(command=None, *, close_on_exit=None, close_on_success=None, close_existing=None, target_client=None, width=None, height=None, x=None, y=None, start_directory=None, title=None, border_lines=None, style=None, border_style=None, environment=None, no_border=None, close_on_any_key=None, no_keys=None) ¶

Display a popup overlay via $ tmux display-popup.

Requires tmux 3.2+ and an attached client. Use ControlMode in tests to provide a client.

Parameters:

command (str, optional) – Shell command to run in the popup.
close_on_exit (bool, optional) – Close popup when command exits (-E flag).
close_on_success (bool, optional) – Close popup only on success exit code (-EE flag, passing -E twice).
close_existing (bool, optional) – Close any existing popup on the client (-C flag).
target_client (str, optional) – Display the popup on this specific client (-c flag). When omitted, tmux selects the client attached to this pane’s session. With multiple clients attached, pass target_client to direct the popup at one of them.
width (int or str, optional) – Popup width (-w flag).
height (int or str, optional) – Popup height (-h flag).
x (int or str, optional) – Popup x position (-x flag).
y (int or str, optional) – Popup y position (-y flag).
start_directory (str or PathLike, optional) – Working directory (-d flag).
title (str, optional) – Popup title (-T flag). Requires tmux 3.3+.
border_lines (str, optional) – Border line style (-b flag). Requires tmux 3.3+.
style (str, optional) – Popup style (-s flag). Requires tmux 3.3+.
border_style (str, optional) – Border style (-S flag). Requires tmux 3.3+.
environment (dict, optional) – Environment variables (-e flag). Requires tmux 3.3+.
no_border (bool, optional) – Open the popup without a border (-B flag). If border_lines is also set, tmux ignores it. Requires tmux 3.3+.
close_on_any_key (bool, optional) – Dismiss the popup on any key press once the inner command has exited (-k flag). Requires tmux 3.6+.
no_keys (bool, optional) – Do not auto-close the popup on any close-trigger keys (-N flag). Requires tmux 3.6+.

Return type:

None

Examples

Not directly testable — popup rendering requires a TTY-backed client. Control-mode provides an attached client for invocation but the popup itself is not visible or verifiable.

>>> with control_mode() as ctl:
...     pane.display_popup(command='true', close_on_exit=True)

paste_buffer(*, buffer_name=None, delete_after=None, linefeed_separator=None, bracket=None, separator=None, no_vis=None) ¶ method[source] method[source] paste_buffer(*, buffer_name=None, delete_after=None, linefeed_separator=None, bracket=None, separator=None, no_vis=None) ¶

Paste a buffer into the pane via $ tmux paste-buffer.

Parameters:

buffer_name (str, optional) – Name of the buffer to paste (-b flag).
delete_after (bool, optional) – Delete the buffer after pasting (-d flag).
linefeed_separator (bool, optional) – Use newline as the line separator instead of carriage return (-r flag).
bracket (bool, optional) – Use bracketed paste mode (-p flag).
separator (str, optional) – Separator between lines (-s flag).
no_vis (bool, optional) – Paste the buffer’s raw bytes without passing them through vis(3) escaping (-S flag). tmux 3.7 escapes pasted content by default; set this to restore the raw behaviour. Requires tmux 3.7+. If used with tmux < 3.7, a warning is issued and the flag is ignored.

Return type:

None

Examples

>>> server.set_buffer('pasted_text')
>>> pane.paste_buffer()

pipe(command=None, *, output_only=None, input_only=None, toggle=None) ¶ method[source] method[source] pipe(command=None, *, output_only=None, input_only=None, toggle=None) ¶

Pipe pane output to a shell command via $ tmux pipe-pane.

Parameters:

command (str, optional) – Shell command to pipe to. If None, stops piping.
output_only (bool, optional) – Only pipe output from the pane (-O flag).
input_only (bool, optional) – Only pipe input to the pane (-I flag).
toggle (bool, optional) – Toggle piping on/off (-o flag).

Return type:

None

Examples

>>> pane.pipe('cat >> /tmp/output.txt')

Stop piping:

>>> pane.pipe()

copy_mode(*, scroll_up=None, exit_on_bottom=None, mouse_drag=None, cancel=None, page_down=None, source_pane=None) ¶ method[source] method[source] copy_mode(*, scroll_up=None, exit_on_bottom=None, mouse_drag=None, cancel=None, page_down=None, source_pane=None) ¶

Enter copy mode via $ tmux copy-mode.

Parameters:

scroll_up (bool, optional) – Start scrolled up one page (-u flag).
exit_on_bottom (bool, optional) – Exit copy mode when scrolling reaches the bottom of the history (-e flag).
mouse_drag (bool, optional) – Start mouse drag (-M flag).
cancel (bool, optional) – Cancel copy mode and any other modes (-q flag).
page_down (bool, optional) – Scroll a page down if already in copy mode (-d flag). Requires tmux 3.5+.
source_pane (str, optional) – Source pane whose contents should be displayed in copy mode (-s flag). Lets you scroll/copy from another pane’s history. Requires tmux 3.2+.

Return type:

None

Examples

>>> pane.copy_mode()

choose_tree(*, sessions_collapsed=None, windows_collapsed=None, format_string=None, filter_expression=None, sort_order=None, reverse=None, zoom=None) ¶ method[source] method[source] choose_tree(*, sessions_collapsed=None, windows_collapsed=None, format_string=None, filter_expression=None, sort_order=None, reverse=None, zoom=None) ¶

Enter tree chooser via $ tmux choose-tree.

Parameters:

sessions_collapsed (bool, optional) – Start with sessions collapsed (-s flag).
windows_collapsed (bool, optional) – Start with windows collapsed (-w flag).
format_string (str, optional) – Format for each item shown in the chooser (-F flag).
filter_expression (str, optional) – Filter expression evaluated per item; only items whose filter expands non-zero are shown (-f flag).
sort_order (str, optional) – Sort field (-O flag).
reverse (bool, optional) – Reverse the sort order (-r flag).
zoom (bool, optional) – Zoom the pane while the chooser is active (-Z flag).

Return type:

None

Examples

>>> pane.choose_tree()

find_window(match_string, *, match_content=None, case_insensitive=None, match_name=None, regex=None, match_title=None) ¶ method[source] method[source] find_window(match_string, *, match_content=None, case_insensitive=None, match_name=None, regex=None, match_title=None) ¶

Search for a window matching a string via $ tmux find-window.

Opens a choose-tree filtered to matching windows.

Parameters:

match_string (str) – String to search for in window names, titles, and content.
match_content (bool, optional) – Match visible pane content (-C flag).
case_insensitive (bool, optional) – Case-insensitive matching (-i flag).
match_name (bool, optional) – Match window name only (-N flag).
regex (bool, optional) – Treat match string as a regex (-r flag).
match_title (bool, optional) – Match pane title (-T flag).

Return type:

None

Examples

>>> pane.find_window('sh')

respawn(*, shell=None, start_directory=None, environment=None, kill=None) ¶ method[source] method[source] respawn(*, shell=None, start_directory=None, environment=None, kill=None) ¶

Respawn the pane process via $ tmux respawn-pane.

Parameters:

shell (str, optional) – Shell command to run in the respawned pane.
start_directory (str or PathLike, optional) – Working directory for the respawned pane (-c flag).
environment (dict, optional) – Environment variables (-e flag).
kill (bool, optional) – Kill the current process before respawning (-k flag). Required if the pane is still active.

Return type:

None

Examples

>>> pane = window.split(shell='sleep 1m')
>>> pane.respawn(kill=True, shell='sh')

move(target, *, vertical=True, detach=True, full_window=None, size=None, before=None) ¶ method[source] method[source] move(target, *, vertical=True, detach=True, full_window=None, size=None, before=None) ¶

Move this pane to another window via $ tmux move-pane.

Similar to join() but invokes the move-pane command directly.

Parameters:

target (str, Pane, or Window) – Target pane or window to move into.
vertical (bool, optional) – Split vertically (-v flag), default True. False for horizontal (-h).
detach (bool, optional) – Do not switch to the target window (-d flag), default True.
full_window (bool, optional) – Use the full window width/height (-f flag).
size (str or int, optional) – Size for the moved pane (-l flag).
before (bool, optional) – Place the pane before the target (-b flag).

Return type:

None

Examples

>>> pane_to_move = window.split(shell='sleep 1m')
>>> w2 = session.new_window(window_name='move_target')
>>> pane_to_move.move(w2)

join(target, *, vertical=True, detach=True, full_window=None, size=None, before=None) ¶ method[source] method[source] join(target, *, vertical=True, detach=True, full_window=None, size=None, before=None) ¶

Join this pane into another window/pane via $ tmux join-pane.

This is the inverse of break_pane().

Parameters:

target (str, Pane, or Window) – Target pane or window to join into.
vertical (bool, optional) – Join vertically (-v flag), default True. Set to False for horizontal (-h).
detach (bool, optional) – Do not switch to the target window (-d flag), default True.
full_window (bool, optional) – Join spanning the full window width/height (-f flag).
size (str or int, optional) – Size for the joined pane (-l flag).
before (bool, optional) – Place the pane before the target (-b flag).

Return type:

None

Examples

>>> pane_to_join = window.split(shell='sleep 1m')
>>> new_window = pane_to_join.break_pane()
>>> pane_to_join.join(window)

break_pane(*, detach=True, window_name=None) ¶ method[source] method[source] break_pane(*, detach=True, window_name=None) ¶

Break this pane out into a new window via $ tmux break-pane.

Parameters:

detach (bool, optional) – Do not switch to the new window (-d flag), default True.
window_name (str, optional) – Name for the new window (-n flag).

Returns:

The newly created window containing the pane.

Return type:

Window

Examples

>>> pane_to_break = window.split(shell='sleep 1m')
>>> new_window = pane_to_break.break_pane(window_name='broken')
>>> new_window.window_name
'broken'

swap(target=None, *, detach=None, move_up=None, move_down=None, keep_zoom=None) ¶ method[source] method[source] swap(target=None, *, detach=None, move_up=None, move_down=None, keep_zoom=None) ¶

Swap this pane with another via $ tmux swap-pane.

Parameters:

target (str or Pane, optional) –
Target pane to swap with. Can be a pane ID string or Pane object. Mutually exclusive with move_up / move_down.

Changed in version 0.56: Now optional; required only when move_up / move_down are not set.
detach (bool, optional) – Do not change the active pane (-d flag).
move_up (bool, optional) – Swap with the pane above (-U flag). Mutually exclusive with target and move_down.
move_down (bool, optional) – Swap with the pane below (-D flag). Mutually exclusive with target and move_up.
keep_zoom (bool, optional) – Keep the window zoomed if it was zoomed (-Z flag).

Return type:

None

Examples

>>> pane1 = window.active_pane
>>> pane2 = window.split()
>>> pane1_id, pane2_id = pane1.pane_id, pane2.pane_id
>>> pane1.swap(pane2)
>>> pane1.refresh()
>>> pane2.refresh()

__init__(server, active_window_index=None, alternate_saved_x=None, alternate_saved_y=None, bracket_paste_flag=None, buffer_name=None, buffer_sample=None, buffer_size=None, client_activity=None, client_cell_height=None, client_cell_width=None, client_control_mode=None, client_created=None, client_discarded=None, client_flags=None, client_height=None, client_key_table=None, client_last_session=None, client_mode_format=None, client_name=None, client_pid=None, client_prefix=None, client_readonly=None, client_session=None, client_termfeatures=None, client_termname=None, client_termtype=None, client_tty=None, client_uid=None, client_user=None, client_utf8=None, client_width=None, client_written=None, command_list_alias=None, command_list_name=None, command_list_usage=None, config_files=None, copy_cursor_line=None, copy_cursor_word=None, copy_cursor_x=None, copy_cursor_y=None, current_file=None, cursor_character=None, cursor_flag=None, cursor_x=None, cursor_y=None, history_bytes=None, history_limit=None, history_size=None, insert_flag=None, keypad_cursor_flag=None, keypad_flag=None, last_window_index=None, line=None, mouse_all_flag=None, mouse_any_flag=None, mouse_button_flag=None, mouse_sgr_flag=None, mouse_standard_flag=None, next_session_id=None, origin_flag=None, pane_active=None, pane_at_bottom=None, pane_at_left=None, pane_at_right=None, pane_at_top=None, pane_bg=None, pane_bottom=None, pane_current_command=None, pane_current_path=None, pane_dead=None, pane_dead_signal=None, pane_dead_status=None, pane_dead_time=None, pane_fg=None, pane_flags=None, pane_floating_flag=None, pane_format=None, pane_height=None, pane_id=None, pane_in_mode=None, pane_index=None, pane_input_off=None, pane_last=None, pane_left=None, pane_marked=None, pane_marked_set=None, pane_mode=None, pane_path=None, pane_pb_progress=None, pane_pb_state=None, pane_pid=None, pane_pipe=None, pane_pipe_pid=None, pane_right=None, pane_search_string=None, pane_start_command=None, pane_start_path=None, pane_synchronized=None, pane_tabs=None, pane_title=None, pane_top=None, pane_tty=None, pane_width=None, pane_x=None, pane_y=None, pane_z=None, pane_zoomed_flag=None, pid=None, scroll_position=None, scroll_region_lower=None, scroll_region_upper=None, search_match=None, selection_end_x=None, selection_end_y=None, selection_start_x=None, selection_start_y=None, session_activity=None, session_alerts=None, session_attached=None, session_attached_list=None, session_created=None, session_format=None, session_group=None, session_group_attached=None, session_group_attached_list=None, session_group_list=None, session_group_many_attached=None, session_group_size=None, session_grouped=None, session_id=None, session_last_attached=None, session_many_attached=None, session_marked=None, session_name=None, session_path=None, session_stack=None, session_windows=None, socket_path=None, start_time=None, synchronized_output_flag=None, uid=None, user=None, version=None, window_active=None, window_active_clients=None, window_active_clients_list=None, window_active_sessions=None, window_active_sessions_list=None, window_activity=None, window_activity_flag=None, window_bell_flag=None, window_bigger=None, window_cell_height=None, window_cell_width=None, window_end_flag=None, window_flags=None, window_format=None, window_height=None, window_id=None, window_index=None, window_last_flag=None, window_layout=None, window_linked=None, window_linked_sessions=None, window_linked_sessions_list=None, window_marked_flag=None, window_name=None, window_offset_x=None, window_offset_y=None, window_panes=None, window_raw_flags=None, window_silence_flag=None, window_stack_index=None, window_start_flag=None, window_visible_layout=None, window_width=None, window_zoomed_flag=None, wrap_flag=None, default_option_scope=OptionScope.Pane, default_hook_scope=OptionScope.Pane) ¶ method[source] method[source] __init__(server, active_window_index=None, alternate_saved_x=None, alternate_saved_y=None, bracket_paste_flag=None, buffer_name=None, buffer_sample=None, buffer_size=None, client_activity=None, client_cell_height=None, client_cell_width=None, client_control_mode=None, client_created=None, client_discarded=None, client_flags=None, client_height=None, client_key_table=None, client_last_session=None, client_mode_format=None, client_name=None, client_pid=None, client_prefix=None, client_readonly=None, client_session=None, client_termfeatures=None, client_termname=None, client_termtype=None, client_tty=None, client_uid=None, client_user=None, client_utf8=None, client_width=None, client_written=None, command_list_alias=None, command_list_name=None, command_list_usage=None, config_files=None, copy_cursor_line=None, copy_cursor_word=None, copy_cursor_x=None, copy_cursor_y=None, current_file=None, cursor_character=None, cursor_flag=None, cursor_x=None, cursor_y=None, history_bytes=None, history_limit=None, history_size=None, insert_flag=None, keypad_cursor_flag=None, keypad_flag=None, last_window_index=None, line=None, mouse_all_flag=None, mouse_any_flag=None, mouse_button_flag=None, mouse_sgr_flag=None, mouse_standard_flag=None, next_session_id=None, origin_flag=None, pane_active=None, pane_at_bottom=None, pane_at_left=None, pane_at_right=None, pane_at_top=None, pane_bg=None, pane_bottom=None, pane_current_command=None, pane_current_path=None, pane_dead=None, pane_dead_signal=None, pane_dead_status=None, pane_dead_time=None, pane_fg=None, pane_flags=None, pane_floating_flag=None, pane_format=None, pane_height=None, pane_id=None, pane_in_mode=None, pane_index=None, pane_input_off=None, pane_last=None, pane_left=None, pane_marked=None, pane_marked_set=None, pane_mode=None, pane_path=None, pane_pb_progress=None, pane_pb_state=None, pane_pid=None, pane_pipe=None, pane_pipe_pid=None, pane_right=None, pane_search_string=None, pane_start_command=None, pane_start_path=None, pane_synchronized=None, pane_tabs=None, pane_title=None, pane_top=None, pane_tty=None, pane_width=None, pane_x=None, pane_y=None, pane_z=None, pane_zoomed_flag=None, pid=None, scroll_position=None, scroll_region_lower=None, scroll_region_upper=None, search_match=None, selection_end_x=None, selection_end_y=None, selection_start_x=None, selection_start_y=None, session_activity=None, session_alerts=None, session_attached=None, session_attached_list=None, session_created=None, session_format=None, session_group=None, session_group_attached=None, session_group_attached_list=None, session_group_list=None, session_group_many_attached=None, session_group_size=None, session_grouped=None, session_id=None, session_last_attached=None, session_many_attached=None, session_marked=None, session_name=None, session_path=None, session_stack=None, session_windows=None, socket_path=None, start_time=None, synchronized_output_flag=None, uid=None, user=None, version=None, window_active=None, window_active_clients=None, window_active_clients_list=None, window_active_sessions=None, window_active_sessions_list=None, window_activity=None, window_activity_flag=None, window_bell_flag=None, window_bigger=None, window_cell_height=None, window_cell_width=None, window_end_flag=None, window_flags=None, window_format=None, window_height=None, window_id=None, window_index=None, window_last_flag=None, window_layout=None, window_linked=None, window_linked_sessions=None, window_linked_sessions_list=None, window_marked_flag=None, window_name=None, window_offset_x=None, window_offset_y=None, window_panes=None, window_raw_flags=None, window_silence_flag=None, window_stack_index=None, window_start_flag=None, window_visible_layout=None, window_width=None, window_zoomed_flag=None, wrap_flag=None, default_option_scope=OptionScope.Pane, default_hook_scope=OptionScope.Pane) ¶

When not a user (custom) option, scope can be implied.

Parameters:

server (Server)
active_window_index (str | None)
alternate_saved_x (str | None)
alternate_saved_y (str | None)
bracket_paste_flag (str | None)
buffer_name (str | None)
buffer_sample (str | None)
buffer_size (str | None)
client_activity (str | None)
client_cell_height (str | None)
client_cell_width (str | None)
client_control_mode (str | None)
client_created (str | None)
client_discarded (str | None)
client_flags (str | None)
client_height (str | None)
client_key_table (str | None)
client_last_session (str | None)
client_mode_format (str | None)
client_name (str | None)
client_pid (str | None)
client_prefix (str | None)
client_readonly (str | None)
client_session (str | None)
client_termfeatures (str | None)
client_termname (str | None)
client_termtype (str | None)
client_tty (str | None)
client_uid (str | None)
client_user (str | None)
client_utf8 (str | None)
client_width (str | None)
client_written (str | None)
command_list_alias (str | None)
command_list_name (str | None)
command_list_usage (str | None)
config_files (str | None)
copy_cursor_line (str | None)
copy_cursor_word (str | None)
copy_cursor_x (str | None)
copy_cursor_y (str | None)
current_file (str | None)
cursor_character (str | None)
cursor_flag (str | None)
cursor_x (str | None)
cursor_y (str | None)
history_bytes (str | None)
history_limit (str | None)
history_size (str | None)
insert_flag (str | None)
keypad_cursor_flag (str | None)
keypad_flag (str | None)
last_window_index (str | None)
line (str | None)
mouse_all_flag (str | None)
mouse_any_flag (str | None)
mouse_button_flag (str | None)
mouse_sgr_flag (str | None)
mouse_standard_flag (str | None)
next_session_id (str | None)
origin_flag (str | None)
pane_active (str | None)
pane_at_bottom (str | None)
pane_at_left (str | None)
pane_at_right (str | None)
pane_at_top (str | None)
pane_bg (str | None)
pane_bottom (str | None)
pane_current_command (str | None)
pane_current_path (str | None)
pane_dead (str | None)
pane_dead_signal (str | None)
pane_dead_status (str | None)
pane_dead_time (str | None)
pane_fg (str | None)
pane_flags (str | None)
pane_floating_flag (str | None)
pane_format (str | None)
pane_height (str | None)
pane_id (str | None)
pane_in_mode (str | None)
pane_index (str | None)
pane_input_off (str | None)
pane_last (str | None)
pane_left (str | None)
pane_marked (str | None)
pane_marked_set (str | None)
pane_mode (str | None)
pane_path (str | None)
pane_pb_progress (str | None)
pane_pb_state (str | None)
pane_pid (str | None)
pane_pipe (str | None)
pane_pipe_pid (str | None)
pane_right (str | None)
pane_search_string (str | None)
pane_start_command (str | None)
pane_start_path (str | None)
pane_synchronized (str | None)
pane_tabs (str | None)
pane_title (str | None)
pane_top (str | None)
pane_tty (str | None)
pane_width (str | None)
pane_x (str | None)
pane_y (str | None)
pane_z (str | None)
pane_zoomed_flag (str | None)
pid (str | None)
scroll_position (str | None)
scroll_region_lower (str | None)
scroll_region_upper (str | None)
search_match (str | None)
selection_end_x (str | None)
selection_end_y (str | None)
selection_start_x (str | None)
selection_start_y (str | None)
session_activity (str | None)
session_alerts (str | None)
session_attached (str | None)
session_attached_list (str | None)
session_created (str | None)
session_format (str | None)
session_group (str | None)
session_group_attached (str | None)
session_group_attached_list (str | None)
session_group_list (str | None)
session_group_many_attached (str | None)
session_group_size (str | None)
session_grouped (str | None)
session_id (str | None)
session_last_attached (str | None)
session_many_attached (str | None)
session_marked (str | None)
session_name (str | None)
session_path (str | None)
session_stack (str | None)
session_windows (str | None)
socket_path (str | None)
start_time (str | None)
synchronized_output_flag (str | None)
uid (str | None)
user (str | None)
version (str | None)
window_active (str | None)
window_active_clients (str | None)
window_active_clients_list (str | None)
window_active_sessions (str | None)
window_active_sessions_list (str | None)
window_activity (str | None)
window_activity_flag (str | None)
window_bell_flag (str | None)
window_bigger (str | None)
window_cell_height (str | None)
window_cell_width (str | None)
window_end_flag (str | None)
window_flags (str | None)
window_format (str | None)
window_height (str | None)
window_id (str | None)
window_index (str | None)
window_last_flag (str | None)
window_layout (str | None)
window_linked (str | None)
window_linked_sessions (str | None)
window_linked_sessions_list (str | None)
window_marked_flag (str | None)
window_name (str | None)
window_offset_x (str | None)
window_offset_y (str | None)
window_panes (str | None)
window_raw_flags (str | None)
window_silence_flag (str | None)
window_stack_index (str | None)
window_start_flag (str | None)
window_visible_layout (str | None)
window_width (str | None)
window_zoomed_flag (str | None)
wrap_flag (str | None)
default_option_scope (OptionScope | None)
default_hook_scope (OptionScope | None)

Return type:

None

_refresh(obj_key, obj_id, list_cmd='list-panes', list_extra_args=None) ¶ method[source] method[source] _refresh(obj_key, obj_id, list_cmd='list-panes', list_extra_args=None) ¶

Refresh dataclass fields from a single list-* row.

Used by the public refresh() methods on Pane, Window, Session, and Client. Each subclass guards its identity field (pane_id, window_id, session_id, client_name) against None before delegating here; this base method enforces the same precondition explicitly so the guarantee survives python -O, where an assert would be stripped.

Raises:

ValueError – When obj_id is None. Surfaces a clear error under python -O, matching the contract of the public refresh() methods.

Parameters:

obj_key (str)
obj_id (str)
list_cmd (ListCmd)
list_extra_args (ListExtraArgs)

Return type:

None

_show_option(option, global_=False, g=False, scope=DEFAULT_OPTION_SCOPE, ignore_errors=None, include_hooks=None, include_inherited=None) ¶ deprecated method[source] deprecated method[source] _show_option(option, global_=False, g=False, scope=DEFAULT_OPTION_SCOPE, ignore_errors=None, include_hooks=None, include_inherited=None) ¶

Return option value for the target.

todo: test and return True/False for on/off string

Parameters:

option (str)
g (bool, optional) –

Deprecated since version 0.50.0: Use global_ instead.
global_ (bool)
scope (OptionScope | _DefaultOptionScope | None)
ignore_errors (bool | None)
include_hooks (bool | None)
include_inherited (bool | None)

Raises:

Return type:

ConvertedValue | None

Examples

>>> import typing as t
>>> from libtmux.common import tmux_cmd
>>> from libtmux.constants import OptionScope

>>> class MyServer(OptionsMixin):
...     socket_name = server.socket_name
...     def cmd(self, cmd: str, *args: object):
...         cmd_args: t.List[t.Union[str, int]] = [cmd]
...         if self.socket_name:
...             cmd_args.insert(0, f"-L{self.socket_name}")
...         cmd_args.insert(0, "-f/dev/null")
...         return tmux_cmd(*cmd_args, *args)
...
...     default_option_scope = OptionScope.Server

>>> MyServer().cmd('new-session', '-d')
<libtmux.common.tmux_cmd object at ...>

>>> MyServer()._show_option('exit-unattached', global_=True)
False

_show_option_raw(option, global_=False, g=False, scope=DEFAULT_OPTION_SCOPE, ignore_errors=None, include_hooks=None, include_inherited=None) ¶ deprecated method[source] deprecated method[source] _show_option_raw(option, global_=False, g=False, scope=DEFAULT_OPTION_SCOPE, ignore_errors=None, include_hooks=None, include_inherited=None) ¶

Return raw option output for target.

Parameters:

option (str)
g (bool, optional) –

Deprecated since version 0.50.0: Use global_ instead.
global_ (bool)
scope (OptionScope | _DefaultOptionScope | None)
ignore_errors (bool | None)
include_hooks (bool | None)
include_inherited (bool | None)

Raises:

Return type:

tmux_cmd

Examples

>>> import typing as t
>>> from libtmux.common import tmux_cmd
>>> from libtmux.constants import OptionScope

>>> class MyServer(OptionsMixin):
...     socket_name = server.socket_name
...     def cmd(self, cmd: str, *args: object):
...         cmd_args: t.List[t.Union[str, int]] = [cmd]
...         if self.socket_name:
...             cmd_args.insert(0, f"-L{self.socket_name}")
...         cmd_args.insert(0, "-f/dev/null")
...         return tmux_cmd(*cmd_args, *args)
...
...     default_option_scope = OptionScope.Server

>>> MyServer().cmd('new-session', '-d')
<libtmux.common.tmux_cmd object at ...>

>>> MyServer()._show_option_raw('exit-unattached', global_=True)
<libtmux.common.tmux_cmd object at ...>

>>> MyServer()._show_option_raw('exit-unattached', global_=True).stdout
['exit-unattached off']

>>> isinstance(MyServer()._show_option_raw('exit-unattached', global_=True).stdout, list)
True

>>> isinstance(MyServer()._show_option_raw('exit-unattached', global_=True).stdout[0], str)
True

_show_options(g=False, global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None) ¶ deprecated method[source] deprecated method[source] _show_options(g=False, global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None) ¶

Return a dict of options for the target.

Parameters:

g (bool, optional) –

Deprecated since version 0.50.0: Use global_ instead.
global_ (bool | None)
scope (OptionScope | _DefaultOptionScope | None)
include_hooks (bool | None)
include_inherited (bool | None)
quiet (bool | None)

Return type:

ExplodedComplexUntypedOptionsDict

Examples

>>> import typing as t
>>> from libtmux.common import tmux_cmd
>>> from libtmux.constants import OptionScope

>>> class MyServer(OptionsMixin):
...     socket_name = server.socket_name
...     def cmd(self, cmd: str, *args: object):
...         cmd_args: t.List[t.Union[str, int]] = [cmd]
...         if self.socket_name:
...             cmd_args.insert(0, f"-L{self.socket_name}")
...         cmd_args.insert(0, "-f/dev/null")
...         return tmux_cmd(*cmd_args, *args)
...
...     default_option_scope = OptionScope.Server

>>> MyServer()._show_options()
{...}

_show_options_dict(g=False, global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None) ¶ deprecated method[source] deprecated method[source] _show_options_dict(g=False, global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None) ¶

Return dict of options for the target.

Parameters:

g (bool, optional) –

Deprecated since version 0.50.0: Use global_ instead.
global_ (bool | None)
scope (OptionScope | _DefaultOptionScope | None)
include_hooks (bool | None)
include_inherited (bool | None)
quiet (bool | None)

Return type:

UntypedOptionsDict

Examples

>>> import typing as t
>>> from libtmux.common import tmux_cmd
>>> from libtmux.constants import OptionScope

>>> class MyServer(OptionsMixin):
...     socket_name = server.socket_name
...     def cmd(self, cmd: str, *args: object):
...         cmd_args: t.List[t.Union[str, int]] = [cmd]
...         if self.socket_name:
...             cmd_args.insert(0, f"-L{self.socket_name}")
...         cmd_args.insert(0, "-f/dev/null")
...         return tmux_cmd(*cmd_args, *args)
...
...     default_option_scope = OptionScope.Server

>>> MyServer()._show_options_dict()
{...}

>>> isinstance(MyServer()._show_options_dict(), dict)
True

_show_options_raw(g=False, global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None, values_only=None) ¶ deprecated method[source] deprecated method[source] _show_options_raw(g=False, global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None, values_only=None) ¶

Return a dict of options for the target.

Parameters:

g (bool, optional) –

Deprecated since version 0.50.0: Use global_ instead.
quiet (bool, optional) –
Suppress errors silently (-q flag).

Added in version 0.56.
values_only (bool, optional) –
Return only option values without names (-v flag).

Added in version 0.56.
global_ (bool | None)
scope (OptionScope | _DefaultOptionScope | None)
include_hooks (bool | None)
include_inherited (bool | None)

Return type:

tmux_cmd

Examples

>>> import typing as t
>>> from libtmux.common import tmux_cmd
>>> from libtmux.constants import OptionScope

>>> class MyServer(OptionsMixin):
...     socket_name = server.socket_name
...     def cmd(self, cmd: str, *args: object):
...         cmd_args: t.List[t.Union[str, int]] = [cmd]
...         if self.socket_name:
...             cmd_args.insert(0, f"-L{self.socket_name}")
...         cmd_args.insert(0, "-f/dev/null")
...         return tmux_cmd(*cmd_args, *args)
...
...     default_option_scope = OptionScope.Server

>>> MyServer()._show_options_raw()
<libtmux.common.tmux_cmd object at ...>

>>> MyServer()._show_options_raw().stdout
[...]

set_hook(hook, value, unset=None, run=None, append=None, g=None, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] set_hook(hook, value, unset=None, run=None, append=None, g=None, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶

Set hook for tmux target.

Wraps $ tmux set-hook <hook> <value>.

Parameters:

hook (str) – hook to set, e.g. ‘aggressive-resize’
value (int | str) – hook command.
unset (bool | None)
run (bool | None)
append (bool | None)
g (bool | None)
global_ (bool | None)
scope (OptionScope | _DefaultOptionScope | None)

Raises:

Return type:

Self

set_hooks(hook, values, *, clear_existing=False, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] set_hooks(hook, values, *, clear_existing=False, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶

Set multiple indexed hooks at once.

Parameters:

hook (str) – Hook name, e.g. ‘session-renamed’
values (HookValues) – Values to set. Can be: - dict[int, str]: {0: ‘cmd1’, 1: ‘cmd2’} - explicit indices - SparseArray[str]: preserves indices from another hook - list[str]: [‘cmd1’, ‘cmd2’] - sequential indices starting at 0
clear_existing (bool) – If True, unset all existing hook values first
global (bool | None) – Use global hooks
scope (OptionScope | None) – Scope for the hook
global_ (bool | None)

Returns:

Returns self for method chaining.

Return type:

Self

Examples

Set hooks with explicit indices:

>>> session.set_hooks('session-renamed', {
...     0: 'display-message "hook 0"',
...     1: 'display-message "hook 1"',
... })
Session($...)

>>> hooks = session.show_hook('session-renamed')
>>> sorted(hooks.keys())
[0, 1]

>>> session.unset_hook('session-renamed')
Session($...)

Set hooks from a list (sequential indices):

>>> session.set_hooks('after-new-window', [
...     'select-pane -t 0',
...     'send-keys "clear" Enter',
... ])
Session($...)

>>> hooks = session.show_hook('after-new-window')
>>> sorted(hooks.keys())
[0, 1]

Replace all existing hooks with clear_existing=True:

>>> session.set_hooks(
...     'session-renamed',
...     {0: 'display-message "new"'},
...     clear_existing=True,
... )
Session($...)

>>> hooks = session.show_hook('session-renamed')
>>> sorted(hooks.keys())
[0]

>>> session.unset_hook('session-renamed')
Session($...)

>>> session.unset_hook('after-new-window')
Session($...)

set_option(option, value, _format=None, prevent_overwrite=None, ignore_errors=None, suppress_warnings=None, append=None, g=None, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] set_option(option, value, _format=None, prevent_overwrite=None, ignore_errors=None, suppress_warnings=None, append=None, g=None, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶

Set option for tmux target.

Wraps $ tmux set-option <option> <value>.

Parameters:

option (str) – option to set, e.g. ‘aggressive-resize’
value (str) – option value. True/False will turn in ‘on’ and ‘off’, also accepts string of ‘on’ or ‘off’ directly.
deprecated: (..) – 0.28: Deprecated by g for global, use global_ instead.
_format (bool | None)
prevent_overwrite (bool | None)
ignore_errors (bool | None)
suppress_warnings (bool | None)
append (bool | None)
g (bool | None)
global_ (bool | None)
scope (OptionScope | _DefaultOptionScope | None)

Raises:

Return type:

Self

Examples

>>> import typing as t
>>> from libtmux.common import tmux_cmd
>>> from libtmux.constants import OptionScope
>>> from libtmux._internal.sparse_array import SparseArray

>>> class MyServer(OptionsMixin):
...     socket_name = server.socket_name
...     def cmd(self, cmd: str, *args: object):
...         cmd_args: t.List[t.Union[str, int]] = [cmd]
...         if self.socket_name:
...             cmd_args.insert(0, f"-L{self.socket_name}")
...         cmd_args.insert(0, "-f/dev/null")
...         return tmux_cmd(*cmd_args, *args)
...
...     default_option_scope = OptionScope.Server

>>> MyServer().set_option('escape-time', 1250)
<libtmux.options.MyServer object at ...>

>>> MyServer()._show_option('escape-time')
1250

>>> MyServer().set_option('escape-time', 495)
<libtmux.options.MyServer object at ...>

>>> MyServer()._show_option('escape-time')
495

show_hook(hook, global_=False, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] show_hook(hook, global_=False, scope=DEFAULT_OPTION_SCOPE) ¶

Return value for a hook.

For array hooks (e.g., session-renamed), returns a SparseArray with hook values at their original indices. Use .keys() for indices and .values() for values.

Parameters:

hook (str) – Hook name to query
global_ (bool)
scope (OptionScope | _DefaultOptionScope | None)

Returns:

Hook value. For array hooks, returns SparseArray.

Return type:

str | int | SparseArray[str] | None

Raises:

Examples

>>> session.set_hook('session-renamed[0]', 'display-message "test"')
Session($...)

>>> hooks = session.show_hook('session-renamed')
>>> isinstance(hooks, SparseArray)
True

>>> sorted(hooks.keys())
[0]

>>> session.unset_hook('session-renamed')
Session($...)

show_hooks(global_=False, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] show_hooks(global_=False, scope=DEFAULT_OPTION_SCOPE) ¶

Return a dict of hooks for the target.

Parameters:

global (bool, optional) – Pass -g flag for global hooks, default False.
scope (OptionScope | _DefaultOptionScope | None, optional) – Hook scope (Server/Session/Window/Pane), defaults to object’s scope.
global_ (bool | None)

Returns:

Dictionary mapping hook names to their values.

Return type:

HookDict

Examples

>>> session.set_hook('session-renamed[0]', 'display-message "test"')
Session($...)

>>> hooks = session.show_hooks()
>>> isinstance(hooks, dict)
True

>>> 'session-renamed[0]' in hooks
True

>>> session.unset_hook('session-renamed')
Session($...)

show_option(option, global_=False, g=False, scope=DEFAULT_OPTION_SCOPE, ignore_errors=None, include_hooks=None, include_inherited=None) ¶ deprecated method[source] deprecated method[source] show_option(option, global_=False, g=False, scope=DEFAULT_OPTION_SCOPE, ignore_errors=None, include_hooks=None, include_inherited=None) ¶

Return option value for the target.

Parameters:

option (str)
g (bool, optional) –

Deprecated since version 0.50.0: Use global_ instead.
global_ (bool)
scope (OptionScope | _DefaultOptionScope | None)
ignore_errors (bool | None)
include_hooks (bool | None)
include_inherited (bool | None)

Raises:

Return type:

Any | None

Examples

>>> import typing as t
>>> from libtmux.common import tmux_cmd
>>> from libtmux.constants import OptionScope

>>> class MyServer(OptionsMixin):
...     socket_name = server.socket_name
...     def cmd(self, cmd: str, *args: object):
...         cmd_args: t.List[t.Union[str, int]] = [cmd]
...         if self.socket_name:
...             cmd_args.insert(0, f"-L{self.socket_name}")
...         cmd_args.insert(0, "-f/dev/null")
...         return tmux_cmd(*cmd_args, *args)
...
...     default_option_scope = OptionScope.Server

>>> MyServer().cmd('new-session', '-d')
<libtmux.common.tmux_cmd object at ...>

>>> MyServer().show_option('exit-unattached', global_=True)
False

show_options(global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None) ¶ method[source] method[source] show_options(global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None) ¶

Return all options for the target.

Parameters:

global (bool, optional) – Pass -g flag for global options, default False.
scope (OptionScope | _DefaultOptionScope | None, optional) – Option scope (Server/Session/Window/Pane), defaults to object’s scope.
include_hooks (bool, optional) – Include hook options (-H flag).
include_inherited (bool, optional) – Include inherited options (-A flag).
quiet (bool, optional) –
Suppress errors silently (-q flag).

Added in version 0.56.
global_ (bool)

Returns:

Dictionary with all options, arrays exploded and values converted.

Return type:

ExplodedComplexUntypedOptionsDict

Raises:

Examples

>>> options = server.show_options()
>>> isinstance(options, dict)
True

>>> 'buffer-limit' in options
True

unset_hook(hook, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] unset_hook(hook, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶

Unset hook for tmux target.

Wraps $ tmux set-hook -u <hook> / $ tmux set-hook -U <hook>

Parameters:

hook (str) – hook to unset, e.g. ‘after-show-environment’
global_ (bool | None)
scope (OptionScope | _DefaultOptionScope | None)

Raises:

Return type:

Self

unset_option(option, unset_panes=None, global_=None, ignore_errors=None, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] unset_option(option, unset_panes=None, global_=None, ignore_errors=None, scope=DEFAULT_OPTION_SCOPE) ¶

Unset option for tmux target.

Wraps $ tmux set-option -u <option> / $ tmux set-option -U <option>

Parameters:

option (str) – option to unset, e.g. ‘aggressive-resize’
unset_panes (bool | None)
global_ (bool | None)
ignore_errors (bool | None)
scope (OptionScope | _DefaultOptionScope | None)

Raises:

Return type:

Self

Examples

>>> import typing as t
>>> from libtmux.common import tmux_cmd
>>> from libtmux.constants import OptionScope

>>> class MyServer(OptionsMixin):
...     socket_name = server.socket_name
...     def cmd(self, cmd: str, *args: object):
...         cmd_args: t.List[t.Union[str, int]] = [cmd]
...         if self.socket_name:
...             cmd_args.insert(0, f"-L{self.socket_name}")
...         cmd_args.insert(0, "-f/dev/null")
...         return tmux_cmd(*cmd_args, *args)
...
...     default_option_scope = OptionScope.Server

>>> MyServer().set_option('escape-time', 1250)
<libtmux.options.MyServer object at ...>

>>> MyServer()._show_option('escape-time')
1250

>>> MyServer().unset_option('escape-time')
<libtmux.options.MyServer object at ...>

>>> isinstance(MyServer()._show_option('escape-time'), int)
True

split_window(target=None, attach=False, start_directory=None, vertical=True, shell=None, size=None, percent=None, environment=None) ¶ deprecated method[source] deprecated method[source] split_window(target=None, attach=False, start_directory=None, vertical=True, shell=None, size=None, percent=None, environment=None) ¶

Split window at pane and return newly created Pane.

Parameters:

attach (bool, optional) – Attach / select pane after creation.
start_directory (str or PathLike, optional) – specifies the working directory in which the new pane is created.
vertical (bool, optional) – split vertically
percent (int, optional) – percentage to occupy with respect to current pane
environment (dict, optional) – Environmental variables for new pane. Passthrough to -e.
target (int | str | None)
shell (str | None)
size (str | int | None)

Return type:

Pane

Notes

Deprecated since version 0.33: Deprecated in favor of split().

resize_pane(adjustment_direction=None, adjustment=None, height=None, width=None, zoom=None, mouse=None, trim_below=None) ¶ deprecated method[source] deprecated method[source] resize_pane(adjustment_direction=None, adjustment=None, height=None, width=None, zoom=None, mouse=None, trim_below=None) ¶

Resize pane, deprecated by Pane.resize().

Deprecated since version 0.28: Deprecated by Pane.resize().

Parameters:

adjustment_direction (ResizeAdjustmentDirection | None)
adjustment (int | None)
height (str | int | None)
width (str | int | None)
zoom (bool | None)
mouse (bool | None)
trim_below (bool | None)

Return type:

Pane