Windows

class libtmux.Window[source]

Bases: Obj, OptionsMixin, HooksMixin

tmux(1) Window [window_manual].

Holds Pane objects.

Parameters:

session (Session)

Examples

>>> window = session.new_window('My project', attach=True)

>>> window
Window(@2 2:My project, Session($... ...))

Windows have panes:

>>> window.panes
[Pane(...)]

>>> window.active_pane
Pane(...)

Relations moving up:

>>> window.session
Session(...)

>>> window.window_id == session.active_window.window_id
True

>>> window == session.active_window
True

>>> window in session.windows
True

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

>>> with session.new_window() as window:
...     pane = window.split()
...     # Do work with the pane
...     # Window will be killed automatically when exiting the context

References

[window_manual]
tmux window. openbsd manpage for TMUX(1).

“Each session has one or more windows linked to it. A window occupies the entire screen and may be split into rectangular panes…”

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

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

refresh()[source]

Refresh window attributes from tmux.

Return type:

None

classmethod from_window_id(server, window_id)[source]

Create Window from existing window_id.

Return type:

Window

Parameters:
property session: Session

Parent session of window.

property panes: QueryList[Pane]

Panes contained by window.

Can be accessed via .panes.get() and .panes.filter()

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

Execute tmux subcommand within window context.

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

Return type:

tmux_cmd

Parameters:

Examples

Create a pane from a window:

>>> window.cmd('split-window', '-P', '-F#{pane_id}').stdout[0]
'%...'

Magic, directly to a Pane:

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

  • target (str, optional) – Optional custom target override. By default, the target is the window ID.

  • cmd (str)

  • args (Any)

Return type:

server.cmd()

select_pane(target_pane)[source]

Select pane and return selected Pane.

$ tmux select-pane.

Return type:

Pane | None

Parameters:

target_pane (str) – ‘target_pane’, ‘-U’ ,’-D’, ‘-L’, ‘-R’, or ‘-l’.

Return type:

Pane

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 on active pane and return the created Pane.

Return type:

Pane

Parameters:

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

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

  • target (int | str | None)

resize(adjustment_direction=None, adjustment=None, height=None, width=None, expand=None, shrink=None)[source]

Resize tmux window.

Return type:

Window

Parameters:

  • adjustment_direction (ResizeAdjustmentDirection, optional) – direction to adjust, Up, Down, Left, Right.

  • adjustment (ResizeAdjustmentDirection, optional)

  • height (int, optional) – resize-window -y dimensions

  • width (int, optional) – resize-window -x dimensions

  • expand (bool) – expand window

  • shrink (bool) – shrink window

Raises:
Return type:

Window

Notes

Three types of resizing are available:

  1. Adjustments: adjustment_direction and adjustment.

  2. Manual resizing: height and / or width.

  3. Expand or shrink: expand or shrink.

last_pane()[source]

Return last pane.

Return type:

Pane | None

select_layout(layout=None)[source]

Select layout for window.

Wrapper for $ tmux select-layout <layout>.

Return type:

Window

Parameters:

layout (str, optional) –

string of the layout, ‘even-horizontal’, ‘tiled’, etc. Entering None (leaving this blank) is same as select-layout with no layout. In recent tmux versions, it picks the most recently set layout.

’even-horizontal’

Panes are spread out evenly from left to right across the window.

’even-vertical’

Panes are spread evenly from top to bottom.

’main-horizontal’

A large (main) pane is shown at the top of the window and the remaining panes are spread from left to right in the leftover space at the bottom.

’main-vertical’

Similar to main-horizontal but the large pane is placed on the left and the others spread from top to bottom along the right.

’tiled’

Panes are spread out as evenly as possible over the window in both rows and columns.

’custom’

custom dimensions (see tmux(1) manpages).

rename_window(new_name)[source]

Rename window.

Return type:

Window

Parameters:

new_name (str) – name of the window

Examples

>>> window = session.active_window

>>> window.rename_window('My project')
Window(@1 1:My project, Session($1 ...))

>>> window.rename_window('New name')
Window(@1 1:New name, Session($1 ...))
kill(all_except=None)[source]

Kill Window.

$ tmux kill-window.

Return type:

None

Parameters:

all_except (bool | None)

Examples

Kill a window:

>>> window_1 = session.new_window()

>>> window_1 in session.windows
True

>>> window_1.kill()

>>> window_1 not in session.windows
True

Kill all windows except the current one:

>>> one_window_to_rule_them_all = session.new_window()

>>> other_windows = session.new_window(
...     ), session.new_window()

>>> all([w in session.windows for w in other_windows])
True

>>> one_window_to_rule_them_all.kill(all_except=True)

>>> all([w not in session.windows for w in other_windows])
True

>>> one_window_to_rule_them_all in session.windows
True
move_window(destination='', session=None)[source]

Move current Window object $ tmux move-window.

Return type:

Window

Parameters:

  • destination (str, optional) – the target window or index to move the window to, default: empty string

  • session (str, optional) – the target session or index to move the window to, default: current session.

new_window(window_name=None, *, start_directory=None, attach=False, window_index='', window_shell=None, environment=None, direction=None)[source]

Create new window respective of current window’s position.

Return type:

Window

Parameters:

See also

Session.new_window()

Examples

>>> window_initial = session.new_window(window_name='Example')
>>> window_initial
Window(@... 2:Example, Session($1 libtmux_...))
>>> window_initial.window_index
'2'

>>> window_before = window_initial.new_window(
... window_name='Window before', direction=WindowDirection.Before)
>>> window_initial.refresh()
>>> window_before
Window(@... 2:Window before, Session($1 libtmux_...))
>>> window_initial
Window(@... 3:Example, Session($1 libtmux_...))

>>> window_after = window_initial.new_window(
... window_name='Window after', direction=WindowDirection.After)
>>> window_initial.refresh()
>>> window_after.refresh()
>>> window_after
Window(@... 4:Window after, Session($1 libtmux_...))
>>> window_initial
Window(@... 3:Example, Session($1 libtmux_...))
>>> window_before
Window(@... 2:Window before, Session($1 libtmux_...))
select()[source]

Select window.

To select a window object asynchrously. If a window object exists and is no longer the current window, w.select_window() will make w the current window.

Return type:

Window

Examples

>>> window = session.active_window
>>> new_window = session.new_window()
>>> session.refresh()
>>> active_windows = [w for w in session.windows if w.window_active == '1']

>>> new_window.window_active == '1'
False

>>> new_window.select()
Window(...)

>>> new_window.window_active == '1'
True
property active_pane: Pane | None

Return attached Pane.

property id: str | None

Alias of Window.window_id.

>>> window.id
'@1'

>>> window.id == window.window_id
True
property name: str | None

Alias of Window.window_name.

>>> window.name
'...'

>>> window.name == window.window_name
True
property index: str | None

Alias of Window.window_index.

>>> window.index
'1'

>>> window.index == window.window_index
True
property height: str | None

Alias of Window.window_height.

>>> window.height.isdigit()
True

>>> window.height == window.window_height
True
property width: str | None

Alias of Window.window_width.

>>> window.width.isdigit()
True

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

Split window and return the created Pane.

Return type:

Pane

Parameters:

  • target (int | str | None)

  • start_directory (StrPath | None)

  • attach (bool)

  • vertical (bool)

  • shell (str | None)

  • size (str | int | None)

  • percent (int | None)

  • environment (dict[str, str] | None)

Notes

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

Changed in version 0.28.0: attach default changed from True to False.

Deprecated since version 0.28.0: percent=25 deprecated in favor of size="25%".

property attached_pane: Pane | None

Return attached Pane.

Notes

Deprecated since version 0.31: Deprecated in favor of active_pane().

select_window()[source]

Select window.

Return type:

Window

Notes

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

kill_window()[source]

Kill the current Window object. $ tmux kill-window.

Return type:

None

Notes

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

set_window_option(option, value)[source]

Set option for tmux window. Deprecated by Window.set_option().

Deprecated since version 0.26: Deprecated by Window.set_option().

Return type:

Window

Parameters:
show_window_options(g=False)[source]

Show options for tmux window. Deprecated by Window.show_options().

Deprecated since version 0.26: Deprecated by Window.show_options().

Return type:

dict[str, Any]

Parameters:

g (bool | None)

show_window_option(option, g=False)[source]

Return option for target window. Deprecated by Window.show_option().

Deprecated since version 0.26: Deprecated by Window.show_option().

Return type:

str | int | None

Parameters:
get(key, default=None)[source]

Return key-based lookup. Deprecated by attributes.

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

Return type:

Any

Parameters:

  • key (str)

  • default (Any | None)

get_by_id(pane_id)[source]

Return pane by id. Deprecated in favor of panes.get().

Deprecated since version 0.16: Deprecated by panes.get().

Return type:

Pane | None

Parameters:

pane_id (str)

where(kwargs)[source]

Filter through panes, return list of Pane.

Deprecated since version 0.16: Deprecated by panes.filter().

Return type:

list[Pane]

Parameters:

kwargs (dict[str, Any])

find_where(kwargs)[source]

Filter through panes, return first Pane.

Deprecated since version 0.16: Slated to be removed in favor of panes.get().

Return type:

Pane | None

Parameters:

kwargs (dict[str, Any])

_list_panes()[source]

Return list of panes (deprecated in favor of panes()).

Deprecated since version 0.16: Slated to be removed in favor of panes.

Return type:

list[dict[str, 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, default_option_scope=OptionScope.Window, default_hook_scope=OptionScope.Window)[source]

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)

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

  • default_option_scope (OptionScope | None)

  • default_hook_scope (OptionScope | None)

Return type:

None

property _panes: list[dict[str, Any]]

Property / alias to return _list_panes().

Deprecated since version 0.16: Slated to be removed in favor of panes.

_show_hook(hook, global_=False, scope=<libtmux.constants._DefaultOptionScope object>)[source]

Return value for the hook.

Return type:

list[str] | None

Parameters:
Raises:
_show_option(option, global_=False, g=False, scope=<libtmux.constants._DefaultOptionScope object>, ignore_errors=None, include_hooks=None, include_inherited=None)[source]

Return option value for the target.

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

Return type:

str | int | bool | None

Parameters:

  • option (str)

  • g (bool, optional) – Pass -g flag, global. Default False.

  • global_ (bool)

  • scope (OptionScope | _DefaultOptionScope | None)

  • ignore_errors (bool | None)

  • include_hooks (bool | None)

  • include_inherited (bool | None)

Raises:

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=<libtmux.constants._DefaultOptionScope object>, ignore_errors=None, include_hooks=None, include_inherited=None)[source]

Return raw option output for target.

Return type:

tmux_cmd

Parameters:

  • option (str)

  • g (bool, optional) – Pass -g flag, global. Default False.

  • global_ (bool)

  • scope (OptionScope | _DefaultOptionScope | None)

  • ignore_errors (bool | None)

  • include_hooks (bool | None)

  • include_inherited (bool | None)

Raises:

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=<libtmux.constants._DefaultOptionScope object>, include_hooks=None, include_inherited=None)[source]

Return a dict of options for the target.

Return type:

dict[str, str | int | list[str | int] | dict[str, list[str | int]] | SparseArray[str | int] | None]

Parameters:

  • g (str, optional) – Pass -g flag for global variable, default False.

  • global_ (bool | None)

  • scope (OptionScope | _DefaultOptionScope | None)

  • include_hooks (bool | None)

  • include_inherited (bool | 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()._show_options()
{...}
_show_options_dict(g=False, global_=False, scope=<libtmux.constants._DefaultOptionScope object>, include_hooks=None, include_inherited=None)[source]

Return dict of options for the target.

Return type:

dict[str, str | None]

Parameters:

  • g (str, optional) – Pass -g flag for global variable, default False.

  • global_ (bool | None)

  • scope (OptionScope | _DefaultOptionScope | None)

  • include_hooks (bool | None)

  • include_inherited (bool | 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()._show_options_dict()
{...}

>>> isinstance(MyServer()._show_options_dict(), dict)
True
_show_options_raw(g=False, global_=False, scope=<libtmux.constants._DefaultOptionScope object>, include_hooks=None, include_inherited=None)[source]

Return a dict of options for the target.

Return type:

tmux_cmd

Parameters:

  • g (str, optional) – Pass -g flag for global variable, default False.

  • global_ (bool | None)

  • scope (OptionScope | _DefaultOptionScope | None)

  • include_hooks (bool | None)

  • include_inherited (bool | 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()._show_options_raw()
<libtmux.common.tmux_cmd object at ...>

>>> MyServer()._show_options_raw().stdout
[...]
run_hook(hook, global_=None, scope=<libtmux.constants._DefaultOptionScope object>)[source]

Run a hook immediately. Useful for testing.

Return type:

Self

Parameters:
set_hook(hook, value, unset=None, run=None, append=None, g=None, global_=None, scope=<libtmux.constants._DefaultOptionScope object>)[source]

Set hook for tmux target.

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

Return type:

Self

Parameters:

  • hook (str) – hook to set, e.g. ‘aggressive-resize’

  • value (str) – hook command.

  • unset (bool | None)

  • run (bool | None)

  • append (bool | None)

  • g (bool | None)

  • global_ (bool | None)

  • scope (OptionScope | _DefaultOptionScope | None)

Raises:
set_hooks(hook, values, *, clear_existing=False, global_=None, scope=<libtmux.constants._DefaultOptionScope object>)[source]

Set multiple indexed hooks at once.

Return type:

Self

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=<libtmux.constants._DefaultOptionScope object>)[source]

Set option for tmux target.

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

Return type:

Self

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:

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=<libtmux.constants._DefaultOptionScope object>)[source]

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.

Return type:

str | int | SparseArray[str] | None

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=<libtmux.constants._DefaultOptionScope object>)[source]

Return a dict of hooks for the target.

Return type:

dict[str, Any]

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=<libtmux.constants._DefaultOptionScope object>, ignore_errors=None, include_hooks=None, include_inherited=None)[source]

Return option value for the target.

Return type:

Any | None

Parameters:

  • option (str)

  • g (bool, optional) – Pass -g flag, global. Default False.

  • global_ (bool)

  • scope (OptionScope | _DefaultOptionScope | None)

  • ignore_errors (bool | None)

  • include_hooks (bool | None)

  • include_inherited (bool | None)

Raises:

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=<libtmux.constants._DefaultOptionScope object>, include_hooks=None, include_inherited=None)[source]

Return all options for the target.

Return type:

dict[str, str | int | list[str | int] | dict[str, list[str | int]] | SparseArray[str | int] | None]

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

  • 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=<libtmux.constants._DefaultOptionScope object>)[source]

Unset hook for tmux target.

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

Return type:

Self

Parameters:

  • hook (str) – hook to unset, e.g. ‘after-show-environment’

  • global_ (bool | None)

  • scope (OptionScope | _DefaultOptionScope | None)

Raises:
unset_option(option, unset_panes=None, global_=None, ignore_errors=None, scope=<libtmux.constants._DefaultOptionScope object>)[source]

Unset option for tmux target.

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

Return type:

Self

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:

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

Return list of Pane for the window.

Deprecated since version 0.16: Slated to be removed in favor of panes.

Return type:

list[Pane]

property children: QueryList[Pane]

Was used by TmuxRelationalObject (but that’s longer used in this class).

Deprecated since version 0.16: Slated to be removed in favor of panes.