Servers¶

Identified by socket path and socket name
May have >1 servers running of tmux at the same time.
Contain Sessions (which contain Windows, which contain Panes)

tmux initializes a server automatically on first running (e.g. executing tmux)

class libtmux.Server ¶ class[source] class[source] class libtmux.Server ¶

Bases: EnvironmentMixin, OptionsMixin, HooksMixin

tmux(1) Server [server_manual].

Server.sessions [Session, …]
- Session.windows [Window, …]
  - Window.panes [Pane, …]
    - Pane

When instantiated stores information on live, running tmux server.

Parameters:

socket_name (str, optional)
socket_path (str, optional)
config_file (str, optional)
colors (str, optional)
on_init (callable, optional)
socket_name_factory (callable, optional)
tmux_bin (str or pathlib.Path, optional)

Examples

>>> server
Server(socket_name=libtmux_test...)

>>> server.sessions
[Session($1 ...)]

>>> server.sessions[0].windows
[Window(@1 1:..., Session($1 ...))]

>>> server.sessions[0].active_window
Window(@1 1:..., Session($1 ...))

>>> server.sessions[0].active_pane
Pane(%1 Window(@1 1:..., Session($1 ...)))

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

>>> with Server() as server:
...     session = server.new_session()
...     # Do work with the session
...     # Server will be killed automatically when exiting the context

References

[server_manual]

CLIENTS AND SESSIONS. openbsd manpage for TMUX(1): “The tmux server manages clients, sessions, windows and panes. Clients are attached to sessions to interact with them, either when they are created with the new-session command, or later with the attach-session command. Each session has one or more windows linked into it. Windows may be linked to multiple sessions and are made up of one or more panes, each of which contains a pseudo terminal.”

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

__init__(socket_name=None, socket_path=None, config_file=None, colors=None, on_init=None, socket_name_factory=None, tmux_bin=None, **kwargs)
¶
method[source]
method[source]
__init__(socket_name=None, socket_path=None, config_file=None, colors=None, on_init=None, socket_name_factory=None, tmux_bin=None, **kwargs)
¶

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

Parameters:

socket_name (str | None)
socket_path (str | Path | None)
config_file (str | None)
colors (int | None)
on_init (Callable[[Server], None] | None)
socket_name_factory (Callable[[], str] | None)
tmux_bin (str | Path | None)
kwargs (Any)

Return type:

None

raise_if_dead() ¶ method[source] method[source] raise_if_dead() ¶

Raise if server not connected.

Raises:

exc.TmuxCommandNotFound – When the tmux binary cannot be found or executed.
subprocess.CalledProcessError – When the tmux server is not running (non-zero exit from list-sessions).
>>> tmux = Server(socket_name="no_exist") –
>>> try: –
... tmux.raise_if_dead() –
... except Exception as e: –
... print(type(e)) –
<class 'subprocess.CalledProcessError'> –

Return type:

None

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

Execute tmux command respective of socket name and file, return output.

Examples

>>> server.cmd('display-message', 'hi')
<libtmux.common.tmux_cmd object at ...>

New session:

>>> server.cmd('new-session', '-d', '-P', '-F#{session_id}').stdout[0]
'$2'

>>> session.cmd('new-window', '-P').stdout[0]
'libtmux...:2.0'

Output of tmux -L … new-window -P -F#{window_id} to a Window object:

>>> Window.from_window_id(window_id=session.cmd(
... 'new-window', '-P', '-F#{window_id}').stdout[0], server=session.server)
Window(@4 3:..., Session($1 libtmux_...))

Create a pane from a window:

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

Output of tmux -L … split-window -P -F#{pane_id} to a Pane object:

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

Parameters:

target (str, optional) – Optional custom target.
cmd (str)
args (Any)

Return type:

common.tmux_cmd

Notes

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

run_shell(command, *, background=None, delay=None, as_tmux_command=None, target_pane=None, cwd=None, show_stderr=None) ¶ method[source] method[source] run_shell(command, *, background=None, delay=None, as_tmux_command=None, target_pane=None, cwd=None, show_stderr=None) ¶

Execute a shell command via $ tmux run-shell.

Parameters:

command (str) – Shell command to execute.
background (bool, optional) – Run in background (-b flag).
delay (str, optional) – Delay before execution (-d flag).
as_tmux_command (bool, optional) – Parse argument as a tmux command instead of a shell command (-C flag).
target_pane (str, optional) – Target pane for output (-t flag).
cwd (str or PathLike, optional) –
Start directory for the shell command (-c flag). When omitted, tmux uses the target client’s current working directory. Requires tmux 3.4+; on older tmux a warning is emitted and the kwarg is ignored.

Note: tmux’s -c is a start directory, not subprocess semantics. If chdir(cwd) fails, tmux falls back to the user’s home directory, then to /, rather than raising — unlike Python’s subprocess.Popen(cwd=) which errors on a failed chdir.

Added in version 0.57.
show_stderr (bool, optional) –
Combine the command’s stderr into the captured output stream (-E flag, maps to JOB_SHOWSTDERR). Requires tmux 3.6+; on older tmux a warning is emitted and the kwarg is ignored.

Added in version 0.57.

Returns:

Stdout lines, or None when background is True. Empty list on tmux 3.3a/3.4 (upstream stdout passthrough was broken until 3.5).

Return type:

list[str] | None

Examples

>>> result = server.run_shell('true')
>>> isinstance(result, list)
True

wait_for(channel, *, lock=None, unlock=None, set_flag=None) ¶ method[source] method[source] wait_for(channel, *, lock=None, unlock=None, set_flag=None) ¶

Wait for, signal, or lock a channel via $ tmux wait-for.

Parameters:

channel (str) – Channel name.
lock (bool, optional) – Lock the channel (-L flag).
unlock (bool, optional) – Unlock the channel (-U flag).
set_flag (bool, optional) – Set the channel flag and wake waiters (-S flag).

Return type:

None

Examples

>>> server.new_session(session_name='wait_test')
Session(...)
>>> server.wait_for('test_channel', set_flag=True)

bind_key(key, command, *, key_table=None, note=None, repeat=None) ¶ method[source] method[source] bind_key(key, command, *, key_table=None, note=None, repeat=None) ¶

Bind a key to a command via $ tmux bind-key.

Parameters:

key (str) – Key to bind (e.g. C-a, F12, M-x).
command (str) – Tmux command to run when key is pressed.
key_table (str, optional) – Key table to bind in (-T flag). Defaults to prefix.
note (str, optional) – Note for the binding (-N flag).
repeat (bool, optional) – Allow the key to repeat (-r flag).

Return type:

None

Examples

>>> server.bind_key('F12', 'display-message test', key_table='root')
>>> server.unbind_key('F12', key_table='root')

unbind_key(key=None, *, key_table=None, all_keys=None, quiet=None) ¶ method[source] method[source] unbind_key(key=None, *, key_table=None, all_keys=None, quiet=None) ¶

Unbind a key via $ tmux unbind-key.

Parameters:

key (str, optional) – Key to unbind. Required unless all_keys is True.
key_table (str, optional) – Key table (-T flag). Defaults to prefix.
all_keys (bool, optional) – Unbind all keys (-a flag).
quiet (bool, optional) – Suppress errors for missing bindings (-q flag).

Return type:

None

Examples

>>> server.bind_key('F11', 'display-message test', key_table='root')
>>> server.unbind_key('F11', key_table='root')

server_access(*, allow=None, deny=None, list_access=None, read_only=None, write=None) ¶ method[source] method[source] server_access(*, allow=None, deny=None, list_access=None, read_only=None, write=None) ¶

Manage server access control via $ tmux server-access.

Requires tmux 3.3+ (introduced in 3.3).

Parameters:

allow (str, optional) – Allow a user (-a flag).
deny (str, optional) – Deny a user (-d flag).
list_access (bool, optional) – List access rules (-l flag).
read_only (bool, optional) – Force the user to attach read-only (-r flag). Implies allow if the user is not already in the ACL. Mutually exclusive with write — tmux rejects -r -w.
write (bool, optional) – Allow the user to attach read-write (-w flag). Implies allow if the user is not already in the ACL. Mutually exclusive with read_only.

Returns:

Access list when list_access is True, None otherwise.

Return type:

list[str] | None

Examples

>>> from libtmux.common import has_gte_version
>>> if has_gte_version("3.3"):
...     result = server.server_access(list_access=True)
...     assert isinstance(result, list)

detach_client(*, target_client=None, shell_command=None) ¶ method[source] method[source] detach_client(*, target_client=None, shell_command=None) ¶

Detach a specific client via $ tmux detach-client.

Maps to $ tmux detach-client [-t <target_client>]. tmux resolves -t over the global client list (see cmd-find.c); the named client may be attached to any session, so this method lives on Server rather than Session.

Parameters:

target_client (str, optional) – Client name (-t flag). When omitted, tmux falls back to the most-recently-active client.
shell_command (str, optional) – Run a shell command on the detached client after detach (-E flag).

Return type:

None

See also

Session.detach_client(): detach every client attached to a session (-s flag).
detach_all_clients(): detach every client on the server (-a flag).

Examples

>>> with control_mode() as ctl:
...     server.detach_client(target_client=ctl.client_name)

detach_all_clients(*, keep_client=None, shell_command=None) ¶ method[source] method[source] detach_all_clients(*, keep_client=None, shell_command=None) ¶

Detach every client on this server via $ tmux detach-client -a.

tmux’s -a always preserves one client; when keep_client is omitted, the most-recently-active client survives.

Parameters:

keep_client (str, optional) – Client to preserve (-t flag). All other clients on the server, regardless of which session they are attached to, are detached.
shell_command (str, optional) – Run a shell command on the detached client(s) after detach (-E flag).

Return type:

None

See also

Session.detach_client(): detach every client attached to a session (-s flag).
detach_client(): detach a single named client (-t flag).

Examples

>>> with control_mode() as ctl:
...     server.detach_all_clients(keep_client=ctl.client_name)

confirm_before(command, *, prompt=None, confirm_key=None, default_yes=None, target_client=None) ¶ method[source] method[source] confirm_before(command, *, prompt=None, confirm_key=None, default_yes=None, target_client=None) ¶

Run a command after confirmation via $ tmux confirm-before.

Always uses -b (background) to avoid blocking the command queue. Use send-keys -K -c <client> to provide the confirmation key.

Requires tmux 3.3+ for -b flag support.

Parameters:

command (str) – Tmux command to run after confirmation.
prompt (str, optional) – Custom prompt text (-p flag).
confirm_key (str, optional) – Key to accept as confirmation (-c flag). Default is y. Requires tmux 3.4+.
default_yes (bool, optional) – Make Enter default to yes (-y flag). Requires tmux 3.4+.
target_client (str, optional) – Target client (-t flag).

Return type:

None

Examples

Interactive confirmation requires tmux 3.4+; the wrapper itself works on 3.3+ but the send-keys -K -c <client> round-trip used here is unreliable on 3.3a:

>>> from libtmux.common import has_gte_version
>>> if has_gte_version("3.4"):
...     with control_mode() as ctl:
...         server.confirm_before(
...             'set -g @cf_test yes',
...             target_client=ctl.client_name,
...         )
...         _ = server.cmd('send-keys', '-K', '-c', ctl.client_name, 'y')
...         result = server.cmd('show-options', '-gv', '@cf_test').stdout[0]
... else:
...     result = 'yes'
>>> result
'yes'

command_prompt(template, *, prompt=None, inputs=None, target_client=None, one_key=None, key_only=None, on_input_change=None, numeric=None, prompt_type=None, expand_format=None, literal=None, bspace_exit=None) ¶ method[source] method[source] command_prompt(template, *, prompt=None, inputs=None, target_client=None, one_key=None, key_only=None, on_input_change=None, numeric=None, prompt_type=None, expand_format=None, literal=None, bspace_exit=None) ¶

Open a command prompt via $ tmux command-prompt.

Always uses -b (background) to avoid blocking the command queue. Use send-keys -K -c <client> to type into the prompt and submit.

Requires tmux 3.3+ for -b flag support.

Parameters:

template (str) – Tmux command template. Use %1, %2 for prompt values.
prompt (str, optional) – Custom prompt text (-p flag). Commas separate multiple prompts.
inputs (str, optional) – Pre-fill prompt input (-I flag). Commas separate multiple.
target_client (str, optional) – Target client (-t flag).
one_key (bool, optional) – Accept only one key press (-1 flag).
key_only (bool, optional) – Only accept key presses, not text (-k flag).
on_input_change (bool, optional) – Run template on each keystroke (-i flag).
numeric (bool, optional) – Accept only numeric input (-N flag).
prompt_type (str, optional) – Prompt type (-T flag).
expand_format (bool, optional) – Pass the template through args_make_commands_prepare (-F flag) so format strings expand. Requires tmux 3.3+.
literal (bool, optional) – Disable splitting prompt on commas — treat it as a single prompt (-l flag). Requires tmux 3.6+.
bspace_exit (bool, optional) – Close the prompt when the user empties it with backspace (-e flag, PROMPT_BSPACE_EXIT). Requires tmux 3.7+ (upstream master).

Return type:

None

Examples

Interactive prompts require tmux 3.4+; the wrapper itself works on 3.3+ but the send-keys -K -c <client> round-trip used here is unreliable on 3.3a:

>>> from libtmux.common import has_gte_version
>>> if has_gte_version("3.4"):
...     with control_mode() as ctl:
...         server.command_prompt(
...             "set -g @cp_test '%1'",
...             target_client=ctl.client_name,
...         )
...         for key in ['h', 'i', 'Enter']:
...             _ = server.cmd('send-keys', '-K', '-c', ctl.client_name, key)
...         result = server.cmd('show-options', '-gv', '@cp_test').stdout[0]
... else:
...     result = 'hi'
>>> result
'hi'

display_menu(*items, title=None, target_pane=None, target_client=None, x=None, y=None, starting_choice=None, border_lines=None, style=None, border_style=None, selected_style=None, mouse=None, stay_open=None) ¶ method[source] method[source] display_menu(*items, title=None, target_pane=None, target_client=None, x=None, y=None, starting_choice=None, border_lines=None, style=None, border_style=None, selected_style=None, mouse=None, stay_open=None) ¶

Display a popup menu via $ tmux display-menu.

Requires a TTY-backed attached client. Control-mode clients have tty.sy=0, which causes menu_prepare() to return NULL. This method cannot be tested with ControlMode.

Parameters:

*items (str) – Menu items as positional args in tmux’s name key command triple format. Use empty strings for separators.
title (str, optional) – Menu title (-T flag).
target_pane (str, optional) – Target pane for format expansion (-t flag).
target_client (str, optional) – Target client (-c flag).
x (int or str, optional) – Menu x position (-x flag).
y (int or str, optional) – Menu y position (-y flag).
starting_choice (int or str, optional) – Pre-selected item index (-C flag). Use - for none. Requires tmux 3.4+.
border_lines (str, optional) – Border line style (-b flag). Requires tmux 3.4+.
style (str, optional) – Menu style (-s flag). Requires tmux 3.4+.
border_style (str, optional) – Border style (-S flag). Requires tmux 3.4+.
selected_style (str, optional) – Style for the currently selected menu item (-H flag). Requires tmux 3.4+.
mouse (bool, optional) – Always enable mouse handling in the menu (-M flag). Requires tmux 3.5+.
stay_open (bool, optional) – Keep the menu open when the mouse is released (-O flag). Requires tmux 3.2+.

Return type:

None

Examples

Cannot run end-to-end (requires a TTY-backed client; see the tty.sy=0 note above). For broader coverage, see tests/test_server.py::test_display_menu_flags.

>>> captured = []
>>> def fake_cmd(name, *args, **_kw):
...     captured.append((name, args))
...     return type('R', (), {'stderr': [], 'stdout': []})()
>>> monkeypatch.setattr(server, 'cmd', fake_cmd)
>>> server.display_menu('First', '1', 'select-pane', title='menu')
>>> captured[0][0]
'display-menu'

show_messages(*, target_client=None, terminals=None, jobs=None) ¶ method[source] method[source] show_messages(*, target_client=None, terminals=None, jobs=None) ¶

Show server message log via $ tmux show-messages.

Without -T/-J, tmux resolves the message log against a target client; if no client is attached and target_client is omitted, tmux raises no current client. Provide target_client (e.g. via ControlMode) when running headless, or use terminals/jobs — those modes don’t require a client.

Parameters:

target_client (str, optional) – Target client (-t flag).
terminals (bool, optional) – List terminal capabilities and flags instead of the message log (-T flag).
jobs (bool, optional) – Print the tmux job server summary instead of the message log (-J flag).

Returns:

Server message log lines (or terminal/job summary when terminals/jobs is set).

Return type:

list[str]

Examples

>>> with control_mode() as ctl:
...     result = server.show_messages(target_client=ctl.client_name)
>>> isinstance(result, list)
True

Display message at server scope via $ tmux display-message.

Like Pane.display_message() but without -t <pane-id> injection. tmux’s cmd-display-message entry uses CMD_FIND_CANFAIL so the target is optional; server-scoped format reads (#{version}, #{socket_path}, #{pid}) resolve without a specific pane handle.

With no client attached and target_client omitted, the status-line path (get_text=False) issues a no current client warning. Use get_text=True for headless reads, or pair with ControlMode.

Notes

Stderr from tmux is reported via warnings.warn(), not raised. tmux uses stderr for both genuine errors and informational messages, and the right escalation depends on tmux version and call shape. 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.

Parameters:

cmd (str) –
Format string to display or evaluate (e.g. "#{version}"). Pass "" together with all_formats=True to dump every variable.

Added in version 0.57.
get_text (bool, optional) –
Return tmux’s stdout instead of rendering to the status line (-p flag).

Added in version 0.57.
format_string (str, optional) –
Alternative format template (-F flag).

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

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

Added in version 0.57.
no_expand (bool, optional) –
Output the literal string without format expansion (-l flag). Requires tmux 3.4+.

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

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

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

Added in version 0.57.

Returns:

Message output if get_text is True, otherwise None.

Return type:

list[str] | None

Examples

Read tmux version without needing a pane handle:

>>> result = server.display_message("#{version}", get_text=True)
>>> isinstance(result, list) and len(result) == 1
True

Dump every format variable:

>>> result = server.display_message("", get_text=True, all_formats=True)
>>> any("session_name=" in line for line in result)
True

show_prompt_history(*, prompt_type=None) ¶ method[source] method[source] show_prompt_history(*, prompt_type=None) ¶

Show prompt history via $ tmux show-prompt-history.

Parameters:: prompt_type (str, optional) – Prompt type to show (-T flag).
Returns:: Prompt history lines.
Return type:: list[str]

Examples

>>> from libtmux.common import has_gte_version
>>> if has_gte_version("3.3"):
...     result = server.show_prompt_history()
... else:
...     result = []
>>> isinstance(result, list)
True

save_buffer(path, *, buffer_name=None, append=None) ¶ method[source] method[source] save_buffer(path, *, buffer_name=None, append=None) ¶

Save a paste buffer to a file via $ tmux save-buffer.

Parameters:

path (str or PathLike) – File path to save the buffer to.
buffer_name (str, optional) – Name of the buffer (-b flag). Defaults to the most recent.
append (bool, optional) – Append to the file instead of overwriting (-a flag).

Return type:

None

Examples

>>> import pathlib
>>> server.set_buffer('save_me')
>>> path = pathlib.Path(request.config.rootdir) / '..' / 'tmp_save.txt'
>>> server.save_buffer(str(path))

load_buffer(path, *, buffer_name=None) ¶ method[source] method[source] load_buffer(path, *, buffer_name=None) ¶

Load a file into a paste buffer via $ tmux load-buffer.

Parameters:

path (str or PathLike) – File path to load into the buffer.
buffer_name (str, optional) – Name of the buffer (-b flag).

Return type:

None

Examples

>>> import pathlib
>>> path = pathlib.Path(request.config.rootdir) / '..' / 'tmp_load.txt'
>>> _ = path.write_text('loaded')
>>> server.load_buffer(str(path), buffer_name='loaded_buf')

list_buffers(*, format_string=None, filter=None) ¶ method[source] method[source] list_buffers(*, format_string=None, filter=None) ¶

List paste buffers via $ tmux list-buffers.

Without arguments returns tmux’s default template (name: N bytes: "sample") — kept for backward compatibility. Pass format_string to request a specific tmux format, or filter to have tmux return only matching buffers.

Parameters:

format_string (str, optional) –
Output template (-F flag). Example: "#{buffer_name}" for raw names only.

Added in version 0.57.
filter (str, optional) –
Filter expression evaluated by tmux (-f flag). Buffers for which the expanded expression is false are omitted. Example: "#{m:libtmux_mcp_*,#{buffer_name}}".

Note: this kwarg shadows the Python builtin filter by design — it mirrors tmux’s own flag name (-f filter) for grep-friendly symmetry between the wrapper and the tmux manual.

Warning

tmux silently expands a malformed filter (unclosed #{...}, unknown format token) to empty, which the filter treats as false — every row is suppressed and no stderr is emitted. A bad filter is indistinguishable from “filter matched nothing”; verify filter syntax against the FORMATS section of tmux(1).

Added in version 0.57.

Returns:

Raw output lines.

Return type:

list[str]

Examples

Default template (backward-compatible):

>>> server.set_buffer('buf_data')
>>> result = server.list_buffers()
>>> len(result) >= 1
True

Project just the names:

>>> server.set_buffer('hello', buffer_name='gap6_demo')
>>> 'gap6_demo' in server.list_buffers(format_string='#{buffer_name}')
True

Filter via tmux:

>>> matches = server.list_buffers(
...     format_string='#{buffer_name}',
...     filter='#{m:gap6_*,#{buffer_name}}',
... )
>>> 'gap6_demo' in matches
True

if_shell(shell_command, tmux_command, *, else_command=None, background=None, target_pane=None) ¶ method[source] method[source] if_shell(shell_command, tmux_command, *, else_command=None, background=None, target_pane=None) ¶

Execute a tmux command conditionally via $ tmux if-shell.

Parameters:

shell_command (str) – Shell command whose exit status determines which tmux command runs.
tmux_command (str) – Tmux command to run if shell_command succeeds (exit 0).
else_command (str, optional) – Tmux command to run if shell_command fails (non-zero exit).
background (bool, optional) – Run the shell command in the background (-b flag).
target_pane (str, optional) – Target pane for format expansion (-t flag).

Return type:

None

Examples

>>> server.if_shell('true', 'set -g @if_test yes')
>>> server.cmd('show-options', '-gv', '@if_test').stdout[0]
'yes'

source_file(path, *, quiet=None, parse_only=None, verbose=None) ¶ method[source] method[source] source_file(path, *, quiet=None, parse_only=None, verbose=None) ¶

Source a tmux configuration file via $ tmux source-file.

Parameters:

path (str or PathLike) – Path to the configuration file.
quiet (bool, optional) – Suppress errors for missing files (-q flag).
parse_only (bool, optional) – Check syntax only, do not execute (-n flag).
verbose (bool, optional) – Show parsed commands (-v flag).

Return type:

None

Examples

>>> import pathlib
>>> conf = pathlib.Path(request.config.rootdir) / '..' / 'tmp_src.conf'
>>> _ = conf.write_text('set -g @test_source yes')
>>> server.source_file(str(conf))

new_session(session_name=None, kill_session=False, attach=False, start_directory=None, window_name=None, window_command=None, x=None, y=None, environment=None, *args, detach_others=None, no_size=None, client_flags=None, **kwargs)
¶
method[source]
method[source]
new_session(session_name=None, kill_session=False, attach=False, start_directory=None, window_name=None, window_command=None, x=None, y=None, environment=None, *args, detach_others=None, no_size=None, client_flags=None, **kwargs)
¶

Create new session, returns new Session.

Uses -P flag to print session info, -F for return formatting returns new Session object.

$ tmux new-session -d will create the session in the background $ tmux new-session -Ad will move to the session name if it already exists. todo: make an option to handle this.

Parameters:

session_name (str, optional) –
```
$ tmux new-session -s <session_name>
```
attach (bool, optional) –
create session in the foreground. attach=False is equivalent to:
```
$ tmux new-session -d
```
kill_session (bool, optional) – Kill current session if $ tmux has-session. Useful for testing workspaces.
start_directory (str or PathLike, optional) – specifies the working directory in which the new session is created.
window_name (str, optional) –
```
$ tmux new-session -n <window_name>
```
window_command (str, optional) – execute a command on starting the session. The window will close when the command exits. NOTE: When this command exits the window will close. This feature is useful for long-running processes where the closing of the window upon completion is desired.
x (int | str, optional) – Force the specified width instead of the tmux default for a detached session
y (int | str, optional) – Force the specified height instead of the tmux default for a detached session
detach_others (bool, optional) –
Detach other clients from the session (-D flag).

Added in version 0.56.
no_size (bool, optional) –
Do not set the initial window size (-X flag).

Added in version 0.56.
client_flags (str, optional) –
Set client flags (-f flag), e.g. no-output, read-only. Requires tmux 3.2+.

Added in version 0.56.
environment (dict[str, str] | None)
args (Any)
kwargs (Any)

Return type:

Session

Raises:

exc.BadSessionName –

Examples

Sessions can be created without a session name (0.14.2+):

>>> server.new_session()
Session($2 2)

Creating them in succession will enumerate IDs (via tmux):

>>> server.new_session()
Session($3 3)

With a session_name:

>>> server.new_session(session_name='my session')
Session($4 my 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.

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
[...]

property clients: QueryList[Client] ¶ property property property clients: QueryList[Client] ¶

Clients attached to this tmux server.

Each attached terminal is a separate Client. server.clients returns the typed view; client.client_readonly, client.client_termtype, client.client_session etc. read tmux’s client_* format tokens.

Returns an empty QueryList when tmux’s list-clients fails for any reason — no running daemon, a missing socket, a permission error, or a subprocess failure. To distinguish “no clients attached” from “tmux unreachable”, call Server.is_alive() or Server.raise_if_dead().

Return type:: QueryList of Client

Examples

>>> with control_mode() as ctl:
...     names = [c.client_name for c in server.clients]
...     ctl.client_name in names
True

set_environment(name, value, *, expand_format=None, hidden=None) ¶ method[source] method[source] set_environment(name, value, *, expand_format=None, hidden=None) ¶

Set environment $ tmux set-environment <name> <value>.

Parameters:

name (str) – The environment variable name, e.g. ‘PATH’.
value (str) – Environment value.
expand_format (bool, optional) –
Expand tmux format strings in the value (-F flag).

Added in version 0.56.
hidden (bool, optional) –
Mark the variable as hidden (-h flag).

Added in version 0.56.

Raises:

ValueError – If tmux returns an error.

Return type:

None

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

search_sessions(*, filter=None) ¶ method[source] method[source] search_sessions(*, filter=None) ¶

Sessions, optionally filtered by tmux before rows are returned.

Like Server.sessions but adds an optional filter kwarg passed to $ tmux list-sessions -f <filter>.

Parameters:

filter (str, optional) –

tmux format expression (-f flag). tmux omits sessions whose expanded expression is false before libtmux builds objects.

Warning

tmux silently expands a malformed filter (unclosed #{...}, unknown format token) to empty, which the filter treats as false — every row is suppressed and no stderr is emitted. A bad filter is indistinguishable from “filter matched nothing”; verify filter syntax against the FORMATS section of tmux(1).

Added in version 0.57.

Return type:

QueryList of Session

See also

Server.sessions: unfiltered QueryList of every session (Python-side .filter() runs against this).
tmux-native Filtering with search_*(): when to pick search_* over QueryList.filter().

Examples

>>> server.new_session(session_name='gap7_alpha')
Session($... gap7_alpha)
>>> server.new_session(session_name='other_beta')
Session($... other_beta)
>>> matches = server.search_sessions(filter='#{m:gap7_*,#{session_name}}')
>>> [s.session_name for s in matches]
['gap7_alpha']

search_windows(*, filter=None) ¶ method[source] method[source] search_windows(*, filter=None) ¶

All windows across sessions, optionally filtered by tmux.

Like Server.windows but with a filter kwarg passed to $ tmux list-windows -a -f <filter>.

Parameters:

filter (str, optional) –

tmux format expression (-f flag).

Warning

Added in version 0.57.

Return type:

QueryList[Window]

See also

Server.windows: unfiltered QueryList of every window across every session (Python-side .filter() runs against this).
tmux-native Filtering with search_*(): when to pick search_* over QueryList.filter().

Examples

>>> sess = server.new_session(session_name='gap7_win_demo')
>>> _ = sess.new_window(window_name='gap7_target')
>>> _ = sess.new_window(window_name='other_window')
>>> matches = server.search_windows(filter='#{m:gap7_*,#{window_name}}')
>>> any(w.window_name == 'gap7_target' for w in matches)
True
>>> any(w.window_name == 'other_window' for w in matches)
False

search_panes(*, filter=None) ¶ method[source] method[source] search_panes(*, filter=None) ¶

All panes across the server, optionally filtered by tmux.

Like Server.panes but with a filter kwarg passed to $ tmux list-panes -a -f <filter>. tmux drops non-matching panes before libtmux builds objects.

Parameters:

filter (str, optional) –

tmux format expression (-f flag). Example: '#{m:%5,#{pane_id}}' (id match) or '#{C/i:libtmux,#{pane_current_command}}' (case-insensitive substring on the current command).

Warning

Added in version 0.57.

Return type:

QueryList[Pane]

See also

Server.panes: unfiltered QueryList of every pane (Python-side .filter() runs against this).
tmux-native Filtering with search_*(): when to pick search_* over QueryList.filter().

Examples

>>> sess = server.new_session(session_name='gap7_pane_demo')
>>> window = sess.active_window
>>> target_pane = window.split()
>>> matches = server.search_panes(
...     filter=f'#{{m:{target_pane.pane_id},#{{pane_id}}}}'
... )
>>> [p.pane_id for p in matches] == [target_pane.pane_id]
True