Panes

class libtmux.Pane[source]

Bases: Obj

tmux(1) Pane [pane_manual].

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

window
Type:

Window

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

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()[source]

Refresh pane attributes from tmux.

Return type:

None

classmethod from_pane_id(server, pane_id)[source]

Create Pane from existing pane_id.

Return type:

Pane

Parameters:
property window: Window

Parent window of pane.

property session: Session

Parent session of pane.

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

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.

Return type:

tmux_cmd

Parameters:

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)[source]

Resize tmux pane.

Return type:

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:

  1. Adjustments: adjustment_direction and adjustment.

  2. Manual resizing: height and / or width.

  3. Zoom / Unzoom: zoom.

capture_pane(start=None, end=None)[source]

Capture text from pane.

$ tmux capture-pane to pane. $ tmux capture-pane -S -10 to pane. :rtype: Union[str, list[str]]

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

Parameters:

  • start ([str,int]) – 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]) – 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

Return type:

str | list[str]

send_keys(cmd, enter=True, suppress_history=False, literal=False)[source]

$ tmux send-keys to the pane.

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

Return type:

None

Parameters:

  • cmd (str) – Text or input into pane

  • 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 True.

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
$
display_message(cmd, get_text=False)[source]

Display message to pane.

Displays a message in target-client status line.

Return type:

Union[str, list[str], None]

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.

kill(all_except=None)[source]

Kill Pane.

$ tmux kill-pane.

Return type:

None

Parameters:

all_except (bool | None)

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
select()[source]

Select pane.

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
select_pane()[source]

Select pane.

Return type:

Pane

Notes

Deprecated since version 0.30: Deprecated in favor of select().

split(target=None, start_directory=None, attach=False, direction=None, full_window_split=None, zoom=None, shell=None, size=None, environment=None)[source]

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

Return type:

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, 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 or percentage to occupy with respect to current window.

  • environment (dict, optional) – Environmental variables for new pane. tmux 3.0+ only. Passthrough to -e.

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)
set_width(width)[source]

Set pane width.

Return type:

Pane

Parameters:

width (int) – pane width, in cells

set_height(height)[source]

Set pane height.

Return type:

Pane

Parameters:

height (int) – height of pain, in cells

enter()[source]

Send carriage return to pane.

$ tmux send-keys send Enter to the pane.

Return type:

Pane

clear()[source]

Clear pane.

Return type:

Pane

reset()[source]

Reset and clear pane history.

Return type:

Pane

property id: str | None

Alias of Pane.pane_id.

>>> pane.id
'%1'

>>> pane.id == pane.pane_id
True
property index: str | None

Alias of Pane.pane_index.

>>> pane.index
'0'

>>> pane.index == pane.pane_index
True
property height: str | None

Alias of Pane.pane_height.

>>> pane.height.isdigit()
True

>>> pane.height == pane.pane_height
True
property width: str | None

Alias of Pane.pane_width.

>>> pane.width.isdigit()
True

>>> pane.width == pane.pane_width
True
property at_top: bool

Typed, converted wrapper around Pane.pane_at_top.

>>> pane.pane_at_top
'1'

>>> pane.at_top
True
property at_bottom: bool

Typed, converted wrapper around Pane.pane_at_bottom.

>>> pane.pane_at_bottom
'1'

>>> pane.at_bottom
True
property at_left: bool

Typed, converted wrapper around Pane.pane_at_left.

>>> pane.pane_at_left
'1'

>>> pane.at_left
True
property at_right: bool

Typed, converted wrapper around Pane.pane_at_right.

>>> pane.pane_at_right
'1'

>>> pane.at_right
True
split_window(target=None, attach=False, start_directory=None, vertical=True, shell=None, size=None, percent=None, environment=None)[source]

Split window at pane and return newly created Pane.

Return type:

Pane

Parameters:

  • attach (bool, optional) – Attach / select pane after creation.

  • start_directory (str, 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. tmux 3.0+ only. Passthrough to -e.

  • target (str | int | None)

  • shell (str | None)

  • size (str | int | None)

Notes

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

get(key, default=None)[source]

Return key-based lookup. Deprecated by attributes. :rtype: Any

Deprecated since version 0.16: Deprecated by attribute lookup, e.g. pane['window_name'] is now accessed via pane.window_name.

Parameters:

  • key (str)

  • default (Any | None)

Return type:

Any

__init__(server, active_window_index=None, alternate_saved_x=None, alternate_saved_y=None, buffer_name=None, buffer_sample=None, buffer_size=None, client_cell_height=None, client_cell_width=None, client_discarded=None, client_flags=None, client_height=None, client_key_table=None, client_name=None, client_pid=None, client_termname=None, client_tty=None, client_uid=None, client_user=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_signal=None, pane_dead_status=None, pane_dead_time=None, pane_fg=None, pane_height=None, pane_id=None, pane_index=None, pane_left=None, pane_pid=None, pane_right=None, pane_search_string=None, pane_start_command=None, pane_start_path=None, pane_tabs=None, pane_top=None, pane_tty=None, pane_width=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_group=None, session_group_attached=None, session_group_list=None, session_group_size=None, session_id=None, session_last_attached=None, session_name=None, session_path=None, session_stack=None, session_windows=None, socket_path=None, start_time=None, uid=None, user=None, version=None, window_active=None, window_active_clients=None, window_active_sessions=None, window_activity=None, window_cell_height=None, window_cell_width=None, window_height=None, window_id=None, window_index=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_stack_index=None, window_width=None, wrap_flag=None)[source]
Parameters:

  • server (Server)

  • active_window_index (str | None)

  • alternate_saved_x (str | None)

  • alternate_saved_y (str | None)

  • buffer_name (str | None)

  • buffer_sample (str | None)

  • buffer_size (str | None)

  • client_cell_height (str | None)

  • client_cell_width (str | None)

  • client_discarded (str | None)

  • client_flags (str | None)

  • client_height (str | None)

  • client_key_table (str | None)

  • client_name (str | None)

  • client_pid (str | None)

  • client_termname (str | None)

  • client_tty (str | None)

  • client_uid (str | None)

  • client_user (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_signal (str | None)

  • pane_dead_status (str | None)

  • pane_dead_time (str | None)

  • pane_fg (str | None)

  • pane_height (str | None)

  • pane_id (str | None)

  • pane_index (str | None)

  • pane_left (str | None)

  • pane_pid (str | None)

  • pane_right (str | None)

  • pane_search_string (str | None)

  • pane_start_command (str | None)

  • pane_start_path (str | None)

  • pane_tabs (str | None)

  • pane_top (str | None)

  • pane_tty (str | None)

  • pane_width (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_group (str | None)

  • session_group_attached (str | None)

  • session_group_list (str | None)

  • session_group_size (str | None)

  • session_id (str | None)

  • session_last_attached (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)

  • uid (str | None)

  • user (str | None)

  • version (str | None)

  • window_active (str | None)

  • window_active_clients (str | None)

  • window_active_sessions (str | None)

  • window_activity (str | None)

  • window_cell_height (str | None)

  • window_cell_width (str | None)

  • window_height (str | None)

  • window_id (str | None)

  • window_index (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_stack_index (str | None)

  • window_width (str | None)

  • wrap_flag (str | None)

Return type:

None

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

Resize pane, deprecated by Pane.resize(). :rtype: Pane

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

Parameters:
Return type:

Pane