feat: Pane.set_title(), configurable tmux_bin, debug logging (#636)

Three independent improvements, plus a bug fix for invalid binary paths.

**Pane.set_title()** wraps `select-pane -T` and returns the `Pane` for
method chaining. A `Pane.title` property aliases `pane_title` for
convenience. The `pane_title` format variable is now included in
libtmux's pane format queries (it had been commented out in formats.py
with an incorrect "removed in 3.1+" note — pane titles are available
in all supported tmux versions).

**Configurable tmux binary** — `Server` accepts a `tmux_bin` parameter
to point at an alternative binary (e.g. wemux, byobu, or a custom
build). The value is threaded through `Server.cmd()`,
`Server.raise_if_dead()`, `fetch_objs()` in `neo.py`, all version-check
functions (`get_version`, `has_version`, `has_gte_version`, etc.), and
`HooksMixin`'s version guards. Child objects (Session, Window, Pane)
inherit it automatically via `server.tmux_bin`. Falls back to
`shutil.which("tmux")` when not set.

**Pre-execution DEBUG logging** — `tmux_cmd` now emits a structured log
record with `extra={"tmux_cmd": ...}` before invoking subprocess, using
`shlex.join` for POSIX-correct quoting. Existing post-execution records
are updated to the same format. Complements the post-execution stdout
log and enables a future dry-run mode.

**Bug fix** — passing a non-existent path as `tmux_bin` previously
surfaced as a raw `FileNotFoundError` from subprocess. Both `tmux_cmd`
and `raise_if_dead` now catch `FileNotFoundError` and raise
`TmuxCommandNotFound` consistently.

Author: tony

CHANGES

@@ -36,6 +36,58 @@ $ uvx --from 'libtmux' --prerelease allow python
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### What's new
+
+#### Pane.set_title() (#636)
+
+New {meth}`~libtmux.Pane.set_title` method wraps `select-pane -T`, and
+{attr}`~libtmux.Pane.title` provides a short alias for
+{attr}`~libtmux.Pane.pane_title`:
+
+```python
+pane.set_title("my-worker")
+pane.pane_title
+# 'my-worker'
+pane.title
+# 'my-worker'
+```
+
+The `pane_title` format variable is now included in libtmux's format queries
+(it was previously excluded).
+
+#### Configurable tmux binary path (#636)
+
+{class}`~libtmux.Server` now accepts a `tmux_bin` parameter to use an
+alternative tmux binary (e.g. wemux, byobu, or a custom build):
+
+```python
+server = Server(socket_name="myserver", tmux_bin="/usr/local/bin/tmux-next")
+```
+
+The path is threaded through {meth}`~libtmux.Server.cmd`,
+{meth}`~libtmux.Server.raise_if_dead`, {func}`~libtmux.neo.fetch_objs`,
+all version-check functions ({func}`~libtmux.common.has_version`,
+{func}`~libtmux.common.has_gte_version`, etc.), and hook scope guards in
+{class}`~libtmux.hooks.HooksMixin`. All child objects (Session, Window,
+Pane) inherit it automatically.
+Falls back to ``shutil.which("tmux")`` at execution time when not set.
+
+#### Pre-execution command logging (#636)
+
+{class}`~libtmux.common.tmux_cmd` now logs the full command line at
+`DEBUG` level *before* execution, complementing the existing post-execution
+stdout logging. This enables diagnostic output and is a prerequisite for a
+future dry-run mode.
+
+### Bug fixes
+
+#### `TmuxCommandNotFound` raised for invalid `tmux_bin` path (#636)
+
+Previously, passing a non-existent binary path raised a raw
+`FileNotFoundError` from `subprocess`. It now raises
+{exc}`~libtmux.exc.TmuxCommandNotFound` consistently, in both
+`tmux_cmd` and `raise_if_dead`.
+
 ## libtmux 0.54.0 (2026-03-07)
 
 ### What's new

src/libtmux/common.py

@@ -9,6 +9,7 @@
 
 import logging
 import re
+import shlex
 import shutil
 import subprocess
 import sys
@@ -248,17 +249,24 @@ class tmux_cmd:
         Renamed from ``tmux`` to ``tmux_cmd``.
     """
 
-    def __init__(self, *args: t.Any) -> None:
-        tmux_bin = shutil.which("tmux")
-        if not tmux_bin:
+    def __init__(self, *args: t.Any, tmux_bin: str | None = None) -> None:
+        resolved = tmux_bin or shutil.which("tmux")
+        if not resolved:
             raise exc.TmuxCommandNotFound
 
-        cmd = [tmux_bin]
+        cmd = [resolved]
         cmd += args  # add the command arguments to cmd
         cmd = [str(c) for c in cmd]
 
         self.cmd = cmd
 
+        if logger.isEnabledFor(logging.DEBUG):
+            cmd_str = shlex.join(cmd)
+            logger.debug(
+                "tmux command dispatched",
+                extra={"tmux_cmd": cmd_str},
+            )
+
         try:
             self.process = subprocess.Popen(
                 cmd,
@@ -269,11 +277,13 @@ def __init__(self, *args: t.Any) -> None:
             )
             stdout, stderr = self.process.communicate()
             returncode = self.process.returncode
+        except FileNotFoundError:
+            raise exc.TmuxCommandNotFound from None
         except Exception:
             logger.error(  # noqa: TRY400
                 "tmux subprocess failed",
                 extra={
-                    "tmux_cmd": subprocess.list2cmdline(cmd),
+                    "tmux_cmd": shlex.join(cmd),
                 },
             )
             raise
@@ -297,7 +307,7 @@ def __init__(self, *args: t.Any) -> None:
             logger.debug(
                 "tmux command completed",
                 extra={
-                    "tmux_cmd": subprocess.list2cmdline(cmd),
+                    "tmux_cmd": shlex.join(cmd),
                     "tmux_exit_code": self.returncode,
                     "tmux_stdout": self.stdout[:100],
                     "tmux_stderr": self.stderr[:100],
@@ -307,7 +317,7 @@ def __init__(self, *args: t.Any) -> None:
             )
 
 
-def get_version() -> LooseVersion:
+def get_version(tmux_bin: str | None = None) -> LooseVersion:
     """Return tmux version.
 
     If tmux is built from git master, the version returned will be the latest
@@ -316,12 +326,19 @@ def get_version() -> LooseVersion:
     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
+        :func:`shutil.which`.
+
     Returns
     -------
     :class:`distutils.version.LooseVersion`
-        tmux version according to :func:`shtuil.which`'s tmux
+        tmux version according to *tmux_bin* if provided, otherwise the
+        system tmux from :func:`shutil.which`
     """
-    proc = tmux_cmd("-V")
+    proc = tmux_cmd("-V", tmux_bin=tmux_bin)
     if proc.stderr:
         if proc.stderr[0] == "tmux: unknown option -- V":
             if sys.platform.startswith("openbsd"):  # openbsd has no tmux -V
@@ -346,93 +363,105 @@ def get_version() -> LooseVersion:
     return LooseVersion(version)
 
 
-def has_version(version: str) -> bool:
+def has_version(version: str, tmux_bin: str | None = None) -> bool:
     """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
     -------
     bool
         True if version matches
     """
-    return get_version() == LooseVersion(version)
+    return get_version(tmux_bin=tmux_bin) == LooseVersion(version)
 
 
-def has_gt_version(min_version: str) -> bool:
+def has_gt_version(min_version: str, tmux_bin: str | None = None) -> bool:
     """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
     -------
     bool
         True if version above min_version
     """
-    return get_version() > LooseVersion(min_version)
+    return get_version(tmux_bin=tmux_bin) > LooseVersion(min_version)
 
 
-def has_gte_version(min_version: str) -> bool:
+def has_gte_version(min_version: str, tmux_bin: str | None = None) -> bool:
     """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
     -------
     bool
         True if version above or equal to min_version
     """
-    return get_version() >= LooseVersion(min_version)
+    return get_version(tmux_bin=tmux_bin) >= LooseVersion(min_version)
 
 
-def has_lte_version(max_version: str) -> bool:
+def has_lte_version(max_version: str, tmux_bin: str | None = None) -> bool:
     """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
     -------
     bool
          True if version below or equal to max_version
     """
-    return get_version() <= LooseVersion(max_version)
+    return get_version(tmux_bin=tmux_bin) <= LooseVersion(max_version)
 
 
-def has_lt_version(max_version: str) -> bool:
+def has_lt_version(max_version: str, tmux_bin: str | None = None) -> bool:
     """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
     -------
     bool
         True if version below max_version
     """
-    return get_version() < LooseVersion(max_version)
+    return get_version(tmux_bin=tmux_bin) < LooseVersion(max_version)
 
 
-def has_minimum_version(raises: bool = True) -> bool:
+def has_minimum_version(raises: bool = True, tmux_bin: str | None = None) -> bool:
     """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
     -------
@@ -456,12 +485,13 @@ def has_minimum_version(raises: bool = True) -> bool:
         Versions will now remove trailing letters per
         `Issue 55 <https://github.com/tmux-python/tmuxp/issues/55>`_.
     """
-    if get_version() < LooseVersion(TMUX_MIN_VERSION):
+    current_version = get_version(tmux_bin=tmux_bin)
+    if current_version < LooseVersion(TMUX_MIN_VERSION):
         if raises:
             msg = (
                 f"libtmux only supports tmux {TMUX_MIN_VERSION} and greater. This "
-                f"system has {get_version()} installed. Upgrade your tmux to use "
-                "libtmux, or use libtmux v0.48.x for older tmux versions."
+                f"system has {current_version} installed. Upgrade your "
+                "tmux to use libtmux, or use libtmux v0.48.x for older tmux versions."
             )
             raise exc.VersionTooLow(msg)
         return False

src/libtmux/formats.py

@@ -3,6 +3,14 @@
 libtmux.formats
 ~~~~~~~~~~~~~~~
 
+:data:`FORMAT_SEPARATOR` is used at runtime by ``neo``, ``pane``, and
+``session``.  The ``*_FORMATS`` lists (``SESSION_FORMATS``,
+``WINDOW_FORMATS``, ``PANE_FORMATS``, etc.) are **reference documentation
+only** — they are not imported or consumed at runtime. The active format
+mechanism is :class:`libtmux.neo.Obj`, whose dataclass fields are
+introspected by :func:`libtmux.neo.get_output_format` to build tmux format
+strings dynamically.
+
 For reference: https://github.com/tmux/tmux/blob/master/format.c
 
 """
@@ -67,7 +75,7 @@
     "pane_index",
     "pane_width",
     "pane_height",
-    # "pane_title",  # removed in 3.1+
+    "pane_title",
     "pane_id",
     "pane_active",
     "pane_dead",

src/libtmux/hooks.py

@@ -70,6 +70,13 @@ def __init__(self, default_hook_scope: OptionScope | None) -> None:
         self.default_hook_scope = default_hook_scope
         self.hooks = Hooks()
 
+    @property
+    def _tmux_bin(self) -> str | None:
+        """Resolve tmux_bin from self (Server) or self.server (Session/Window/Pane)."""
+        return getattr(self, "tmux_bin", None) or getattr(
+            getattr(self, "server", None), "tmux_bin", None
+        )
+
     def run_hook(
         self,
         hook: str,
@@ -89,7 +96,7 @@ def run_hook(
             assert scope in HOOK_SCOPE_FLAG_MAP
 
             flag = HOOK_SCOPE_FLAG_MAP[scope]
-            if flag in {"-p", "-w"} and has_lt_version("3.2"):
+            if flag in {"-p", "-w"} and has_lt_version("3.2", tmux_bin=self._tmux_bin):
                 warnings.warn(
                     "Scope flag '-w' and '-p' requires tmux 3.2+. Ignoring.",
                     stacklevel=2,
@@ -168,7 +175,7 @@ def set_hook(
             assert scope in HOOK_SCOPE_FLAG_MAP
 
             flag = HOOK_SCOPE_FLAG_MAP[scope]
-            if flag in {"-p", "-w"} and has_lt_version("3.2"):
+            if flag in {"-p", "-w"} and has_lt_version("3.2", tmux_bin=self._tmux_bin):
                 warnings.warn(
                     "Scope flag '-w' and '-p' requires tmux 3.2+. Ignoring.",
                     stacklevel=2,
@@ -221,7 +228,7 @@ def unset_hook(
             assert scope in HOOK_SCOPE_FLAG_MAP
 
             flag = HOOK_SCOPE_FLAG_MAP[scope]
-            if flag in {"-p", "-w"} and has_lt_version("3.2"):
+            if flag in {"-p", "-w"} and has_lt_version("3.2", tmux_bin=self._tmux_bin):
                 warnings.warn(
                     "Scope flag '-w' and '-p' requires tmux 3.2+. Ignoring.",
                     stacklevel=2,
@@ -286,7 +293,7 @@ def show_hooks(
             assert scope in HOOK_SCOPE_FLAG_MAP
 
             flag = HOOK_SCOPE_FLAG_MAP[scope]
-            if flag in {"-p", "-w"} and has_lt_version("3.2"):
+            if flag in {"-p", "-w"} and has_lt_version("3.2", tmux_bin=self._tmux_bin):
                 warnings.warn(
                     "Scope flag '-w' and '-p' requires tmux 3.2+. Ignoring.",
                     stacklevel=2,
@@ -344,7 +351,7 @@ def _show_hook(
             assert scope in HOOK_SCOPE_FLAG_MAP
 
             flag = HOOK_SCOPE_FLAG_MAP[scope]
-            if flag in {"-p", "-w"} and has_lt_version("3.2"):
+            if flag in {"-p", "-w"} and has_lt_version("3.2", tmux_bin=self._tmux_bin):
                 warnings.warn(
                     "Scope flag '-w' and '-p' requires tmux 3.2+. Ignoring.",
                     stacklevel=2,

src/libtmux/neo.py

@@ -103,6 +103,7 @@ class Obj:
     pane_start_command: str | None = None
     pane_start_path: str | None = None
     pane_tabs: str | None = None
+    pane_title: str | None = None
     pane_top: str | None = None
     pane_tty: str | None = None
     pane_width: str | None = None
@@ -318,7 +319,10 @@ def fetch_objs(
             },
         )
 
-    proc = tmux_cmd(*tmux_cmds)  # output
+    proc = tmux_cmd(
+        *tmux_cmds,
+        tmux_bin=server.tmux_bin,
+    )
 
     if proc.stderr:
         raise exc.LibTmuxException(proc.stderr)