Utilities

Helper methods and mixins for libtmux.

libtmux.common

libtmux.common.TMUX_MIN_VERSION = '3.2a'
data
data
libtmux.common.TMUX_MIN_VERSION = '3.2a'

Minimum version of tmux required to run libtmux

libtmux.common.TMUX_MAX_VERSION = '3.7'
data
data
libtmux.common.TMUX_MAX_VERSION = '3.7'

Most recent version of tmux supported

class libtmux.common.CmdProtocol
class[source]
class[source]
class libtmux.common.CmdProtocol

Bases: Protocol

Command protocol for tmux command.

__init__(*args, **kwargs)
method[source]
method[source]
__init__(*args, **kwargs)
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
_is_protocol = True
attribute
attribute
_is_protocol = True
class libtmux.common.CmdMixin
class[source]
class[source]
class libtmux.common.CmdMixin

Bases: object

Command mixin for tmux command.

cmd: CmdProtocol
attribute
attribute
cmd: CmdProtocol
class libtmux.common.EnvironmentMixin
class[source]
class[source]
class libtmux.common.EnvironmentMixin

Bases: object

Mixin for manager session and server level environment variables in tmux.

cmd: Callable[[t.Any, t.Any], tmux_cmd]
attribute
attribute
cmd: Callable[[t.Any, t.Any], tmux_cmd]
__init__(add_option=None)
method[source]
method[source]
__init__(add_option=None)
Parameters:

add_option (str | None)

Return type:

None

_add_option = None
attribute
attribute
_add_option = None
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

unset_environment(name)
method[source]
method[source]
unset_environment(name)

Unset environment variable $ tmux set-environment -u <name>.

Parameters:

name (str) – The environment variable name, e.g. ‘PATH’.

Raises:

ValueError – If tmux returns an error.

Return type:

None

remove_environment(name)
method[source]
method[source]
remove_environment(name)

Remove environment variable $ tmux set-environment -r <name>.

Parameters:

name (str) – The environment variable name, e.g. ‘PATH’.

Raises:

ValueError – If tmux returns an error.

Return type:

None

show_environment()
method[source]
method[source]
show_environment()

Show environment $ tmux show-environment -t [session].

Return dict of environment variables for the session.

Changed in version 0.13: Removed per-item lookups. Use libtmux.common.EnvironmentMixin.getenv().

Returns:

environmental variables in dict, if no name, or str if name entered.

Return type:

dict

getenv(name)
method[source]
method[source]
getenv(name)

Show environment variable $ tmux show-environment -t [session] <name>.

Return the value of a specific variable if the name is specified.

Added in version 0.13.

Parameters:

name (str) – the environment variable name. such as ‘PATH’.

Returns:

Value of environment variable

Return type:

str

libtmux.common.raise_if_stderr(proc, subcommand)
function[source]
function[source]
libtmux.common.raise_if_stderr(proc, subcommand)

Raise LibTmuxException tagged with the tmux subcommand on stderr.

Centralizes the if proc.stderr: raise exc.LibTmuxException(proc.stderr) pattern scattered across the wrappers. Tags the exception with the originating tmux subcommand so downstream consumers (e.g. libtmux-mcp’s handle_tool_errors) keep the “which tmux command failed” context.

Parameters:

  • proc (tmux_cmd) – Result of a Server.cmd() / Session.cmd() / etc. call.

  • subcommand (str) – The tmux subcommand the wrapper invoked, e.g. "last-window", "swap-pane". Surfaces in str(exc) as a "<subcommand>: …" prefix.

Raises:

LibTmuxException – When proc.stderr is non-empty.

Return type:

None

Examples

>>> from libtmux.common import raise_if_stderr
>>> from libtmux import exc
>>> proc = session.cmd("display-message", "-p", "#{session_id}")
>>> raise_if_stderr(proc, "display-message")  # no stderr → no raise

Added in version 0.57.

class libtmux.common.tmux_cmd
class[source]
class[source]
class libtmux.common.tmux_cmd

Bases: object

Run any tmux(1) command through subprocess.

Examples

Create a new session, check for error:

>>> proc = tmux_cmd(f'-L{server.socket_name}', 'new-session', '-d', '-P', '-F#S')
>>> if proc.stderr:
...     raise exc.LibTmuxException(
...         'Command: %s returned error: %s' % (proc.cmd, proc.stderr)
...     )
...

>>> print(f'tmux command returned {" ".join(proc.stdout)}')
tmux command returned 2

Equivalent to:

$ tmux new-session -s my session

Notes

Changed in version 0.8: Renamed from tmux to tmux_cmd.

__init__(*args, tmux_bin=None)
method[source]
method[source]
__init__(*args, tmux_bin=None)
Parameters:
Return type:

None

exception libtmux.common._TmuxVersionUnavailable
exception[source]
exception[source]
exception libtmux.common._TmuxVersionUnavailable

Bases: Exception

Internal signal: this tmux predates the -V flag (pre-1.7).

libtmux.common._no_version_flag_fallback()
function[source]
function[source]
libtmux.common._no_version_flag_fallback()

Return a synthetic version string when tmux lacks -V.

OpenBSD ships a -V-less base tmux, so assume the maximum supported version; any other platform is genuinely too old.

Return type:

str

libtmux.common._query_version(tmux_bin=None)
function[source]
function[source]
libtmux.common._query_version(tmux_bin=None)

Return the raw tmux -V version token, letter suffix intact.

Runs tmux -V and extracts the version token (e.g. "3.7a", "master", "next-3.8"). Not memoized – get_version() and get_version_str() each cache their own result on top of this query.

Parameters:

tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

Returns:

Raw version token from tmux -V.

Return type:

str

Raises:
libtmux.common.get_version_str(tmux_bin=None)
function[source]
function[source]
libtmux.common.get_version_str(tmux_bin=None)

Return the tmux version string verbatim, preserving letter suffixes.

get_version() normalizes point releases for numeric comparison ("3.7a" becomes LooseVersion("3.7")). This helper keeps the raw suffix, so callers can distinguish patch releases whose behavior differs – for example the tmux 3.7 break-pane crash, reverted in 3.7a.

Parameters:

tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

Returns:

Raw tmux version, e.g. "3.7a". Git builds return "master"; OpenBSD base tmux returns "<max>-openbsd".

Return type:

str

Examples

>>> isinstance(get_version_str(), str)
True

Notes

Memoized via functools.cache(), keyed on tmux_bin, independently of get_version(). Call get_version_str.cache_clear() after swapping the tmux binary.

libtmux.common.get_version(tmux_bin=None)
function[source]
function[source]
libtmux.common.get_version(tmux_bin=None)

Return tmux version.

If tmux is built from git master, the version returned will be the latest version appended with -master, e.g. 2.4-master.

If using OpenBSD’s base system tmux, the version will have -openbsd appended to the latest version, e.g. 2.4-openbsd.

Parameters:

tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux from shutil.which().

Returns:

tmux version according to tmux_bin if provided, otherwise the system tmux from shutil.which()

Return type:

distutils.version.LooseVersion

Notes

Memoized via functools.cache(), keyed on the tmux_bin argument (None is a distinct key from any explicit path), independently of get_version_str(). The cache is sticky across PATH changes and on-disk binary swaps when tmux_bin is None or the same path string – call get_version.cache_clear() to invalidate. Tests that monkey-patch tmux_cmd should call cache_clear() before asserting parsed-version behavior.

libtmux.common.has_version(version, tmux_bin=None)
function[source]
function[source]
libtmux.common.has_version(version, tmux_bin=None)

Return True if tmux version installed.

Parameters:

  • version (str) – version number, e.g. ‘3.2a’

  • tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

Returns:

True if version matches

Return type:

bool

libtmux.common.has_gt_version(min_version, tmux_bin=None)
function[source]
function[source]
libtmux.common.has_gt_version(min_version, tmux_bin=None)

Return True if tmux version greater than minimum.

Parameters:

  • min_version (str) – tmux version, e.g. ‘3.2a’

  • tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

Returns:

True if version above min_version

Return type:

bool

libtmux.common.has_gte_version(min_version, tmux_bin=None)
function[source]
function[source]
libtmux.common.has_gte_version(min_version, tmux_bin=None)

Return True if tmux version greater or equal to minimum.

Parameters:

  • min_version (str) – tmux version, e.g. ‘3.2a’

  • tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

Returns:

True if version above or equal to min_version

Return type:

bool

libtmux.common.has_lte_version(max_version, tmux_bin=None)
function[source]
function[source]
libtmux.common.has_lte_version(max_version, tmux_bin=None)

Return True if tmux version less or equal to minimum.

Parameters:

  • max_version (str) – tmux version, e.g. ‘3.2a’

  • tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

Returns:

True if version below or equal to max_version

Return type:

bool

libtmux.common.has_lt_version(max_version, tmux_bin=None)
function[source]
function[source]
libtmux.common.has_lt_version(max_version, tmux_bin=None)

Return True if tmux version less than minimum.

Parameters:

  • max_version (str) – tmux version, e.g. ‘3.2a’

  • tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

Returns:

True if version below max_version

Return type:

bool

libtmux.common.has_minimum_version(raises=True, tmux_bin=None)
function[source]
function[source]
libtmux.common.has_minimum_version(raises=True, tmux_bin=None)

Return True if tmux meets version requirement. Version >= 3.2a.

Parameters:

  • raises (bool) – raise exception if below minimum version requirement

  • tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

Returns:

True if tmux meets minimum required version.

Return type:

bool

Raises:

libtmux.exc.VersionTooLow – tmux version below minimum required for libtmux

Notes

Changed in version 0.49.0: Minimum version bumped to 3.2a. For older tmux, use libtmux v0.48.x.

Changed in version 0.7.0: No longer returns version, returns True or False

Changed in version 0.1.7: Versions will now remove trailing letters per Issue 55.

libtmux.common.session_check_name(session_name)
function[source]
function[source]
libtmux.common.session_check_name(session_name)

Raise exception session name invalid, modeled after tmux function.

tmux(1) session names may not be empty, or include periods or colons. These delimiters are reserved for noting session, window and pane.

Parameters:

session_name (str) – Name of session.

Raises:

exc.BadSessionName – Invalid session name.

Return type:

None

libtmux.common.get_libtmux_version()
function[source]
function[source]
libtmux.common.get_libtmux_version()

Return libtmux version is a PEP386 compliant format.

Returns:

libtmux version

Return type:

distutils.version.LooseVersion