v0.61.0 - tmux 3.7a and 3.7b test fixes

libtmux 0.61.0 hardens support for the tmux 3.7 patch line. It fixes Pane.break_pane() naming broken-out windows libtmux instead of tmux's own default on tmux 3.7a/3.7b, and adds get_version_str() for reading the raw tmux version with its point-release suffix intact.

Highlights

• Fix — break_pane() keeps tmux's default window name on 3.7a/3.7b (#699). Breaking a pane into a new window without an explicit window_name left it named libtmux on tmux 3.7a/3.7b; it now keeps tmux's own default (typically the running command). Passing window_name is unaffected.
• New — get_version_str() (#699). libtmux.common.get_version_str() returns the running tmux version verbatim, keeping the point-release suffix ("3.7a") that get_version() strips for numeric comparison — useful for telling patch releases apart, e.g. 3.7 from 3.7a.
• tmux 3.7a/3.7b test compatibility (#698). The test suite now passes against tmux 3.7a and 3.7b, which CI also exercises.

What's Changed

• docs: lead topic pages with the concept, add docs voice guide by @tony in #696
• Fix window-name test for tmux 3.7a/3.7b and add them to CI by @tony in #698
• Fix break_pane forcing 'libtmux' window name on tmux 3.7a/3.7b by @tony in #699

Full Changelog: v0.60.0...v0.61.0

v0.60.0 - tmux 3.7 parity

libtmux 0.60.0 completes tmux 3.7 feature parity. Building on the 3.7 compatibility shipped in 0.59.0, it adds first-class floating panes via Pane.new_pane() and Window.new_pane(), types tmux 3.7's new server, session, window, and pane options, exposes the new pane format variables on Pane, and wraps tmux 3.7's new command flags. Every 3.7-only surface is version-gated, so tmux 3.2a–3.6 keep working unchanged.

What's new

Floating panes (new-pane) (#694)

tmux 3.7's flagship feature is now reachable through Window.new_pane() and Pane.new_pane(). A floating pane sits above the tiled layout like a popup but behaves like a real pane. Pass width/height to size it and x/y to position it, alongside the usual shell, start_directory, environment, zoom, and empty, plus style, active_border_style, inactive_border_style, message, and keep (remain-on-exit). The returned Pane reports pane_floating_flag == "1". Requires tmux 3.7+; see the floating panes guide.

Typed tmux 3.7 options (#694)

The option dataclasses now type tmux 3.7's new options. On the server, get-clipboard; on the session, focus-follows-mouse, message-format, and prompt-command-cursor-style; and on the window, the copy-mode line-number options, the tree-mode preview options, and the window-pane status formats (of these, tree-mode-preview-format is also pane-scoped). The pane remain-on-exit option gained tmux 3.7's key value, and pane-active-border-style / pane-border-style (widened to pane scope in 3.7) now type on the pane too.

tmux 3.7 pane format variables (#694)

Pane now exposes tmux 3.7's new pane format variables: the floating-pane geometry and flags (pane_floating_flag, pane_x, pane_y, pane_z, pane_flags, pane_zoomed_flag), the OSC 9;4 progress report (pane_pb_progress, pane_pb_state), pane_pipe_pid, and the bracket_paste_flag and synchronized_output_flag screen-mode flags. Each is version-gated, so the format template stays clean on tmux 3.2a–3.6.

tmux 3.7 command flags (#694)

New tmux 3.7 flags are exposed on existing wrappers: Pane.capture_pane() gains hyperlinks (-H), line_numbers (-L), and line_flags (-F); Window.split() / Pane.split() gain empty (-E) plus style/active_border_style/inactive_border_style (-s/-S/-R), message (-m), and keep (-k); Session.kill() gains group (-g); and Pane.paste_buffer() gains no_vis (-S). On the server, Server.command_prompt() gains no_freeze (-C), Server.list_keys() gains format_ (-F), Server.run_shell() accepts trailing args expanded as #{1}/#{2}, and Server.refresh_client() gains request_clipboard (-l). Each warns and is ignored on tmux < 3.7.

Compatibility

Purely additive — no breaking changes. New 3.7 parameters are gated on tmux's reported version; unsupported flags warn and are ignored on older tmux, and floating-pane creation raises there because new-pane does not exist before 3.7. tmux 3.2a–3.6 remain supported and tested.

Links: Changelog · API docs · Floating panes guide · PyPI

What's Changed

• Add tmux 3.7 feature parity: floating panes, options, formats by @tony in #694

Full Changelog: v0.59.0...v0.60.0

v0.59.0 - tmux 3.7 support

What's Changed

• Restore compatibility with tmux 3.7 by @tony in #693

Full Changelog: v0.58.1...v0.59.0

v0.58.1 - pytest 9.1 compatibility

What's Changed

libtmux 0.58.1 restores compatibility with pytest 9.1. libtmux's bundled pytest plugin no longer aborts at import time, so projects that rely on libtmux's fixtures can move to the latest pytest without their test suite failing before collection.

pytest 9.1 rejects marks applied to fixture functions during plugin import — before collection begins. Because the plugin ships as an installed entry point, this aborted the entire test session for any downstream project that has libtmux installed (for example, tmuxp). The fix removes a no-op skipif mark from the zshrc fixture; the real zsh handling lives in conftest.py and is unchanged, so behavior is identical for zsh and non-zsh users.

This is a bug-fix-only patch release, per libtmux's pre-1.0 version policy (patch = bug fixes; minor = features/breaking changes).

See the CHANGES entry for full details.

• Fix pytest 9.1 fixture-mark import failure by @tony in #687

Full Changelog: v0.58.0...v0.58.1

v0.58.0

libtmux 0.58.0 fixes subprocess output decoding on non-UTF-8 locales. Both tmux_cmd and ControlMode now enforce UTF-8 when reading tmux output, matching tmux's own encoding contract.

Fixes

Subprocess encoding on non-UTF-8 locales (#679)

tmux_cmd and ControlMode now pass encoding="utf-8" to subprocess.Popen, ensuring tmux output is decoded correctly regardless of the system locale. Previously, on non-UTF-8 locales, the FORMAT_SEPARATOR character (U+241E) was corrupted during decoding, causing list accessors (Server.sessions, etc.) to return empty results.

Links: Changelog · API docs · PyPI

Full Changelog: v0.57.1...v0.58.0

v0.57.1

What's Changed

libtmux 0.57.1 restores the lenient-by-default behavior for Server.sessions and Server.clients. Both accessors return an empty QueryList on tmux failure (socket permission errors, subprocess crashes, missing daemon) again,
matching the contract Server.sessions has carried since 0.17.0.

Code written for 0.57.0 with try/except LibTmuxException around these accessors keeps working — the except clause just becomes unreachable. For an explicit connectivity signal, use Server.is_alive() or Server.raise_if_dead().

Server.search_sessions, Server.search_windows, and Server.search_panes continue to raise — they take a caller-supplied filter where a tmux error carries meaningful signal.

See the CHANGES entry for full details.

• Server(fix[sessions,clients]): Return empty on tmux errors by @tony in #677

Full Changelog: v0.57.0...v0.57.1

v0.57.0

libtmux 0.57.0 broadens tmux support around attached clients, tmux-native filtering, and format-token fields. Client gives callers a typed object for attached terminals, search_*() methods let tmux return only matching sessions, windows, and panes, and more tmux format tokens are exposed as typed attributes. LibTmuxException now records which tmux subcommand failed, making command errors easier to handle downstream.

Full release notes: https://libtmux.git-pull.com/history.html#libtmux-0-57-0-2026-05-17

Breaking changes

LibTmuxException string form gains a subcommand prefix

When LibTmuxException is raised from a libtmux method, str(exc) now begins with the originating tmux subcommand name followed by ": ". An error from Session.last_window() used to render as "can't find window" and now renders as "last-window: can't find window".

exc.args[0] still carries the original tmux error text, and the new LibTmuxException.subcommand attribute exposes the tmux subcommand name as a separate field.

The error-payload type also changed: exc.args[0] is now str, joined with "\n" when tmux emitted multiple stderr lines. Previously it was list[str]. Code that pattern-matches on str(exc) exactly, anchors a regex with ^ against the old shape, or indexes exc.args[0] element-by-element will no longer match. Substring matches ("can't find" in str(exc)) and unanchored re.search patterns continue to work unchanged.

See the migration guide for the upgrade pattern.

Server.sessions, Server.clients, Server.search_sessions raise on tmux errors

Previously, a tmux command failure under these accessors could return an empty QueryList indistinguishable from "no sessions / no clients attached" or "filter matched nothing". They now let LibTmuxException propagate for real tmux failures.

Genuine empty results — a server with no attached clients, or a filter that matched zero sessions — still return an empty QueryList. A missing or not-yet-started tmux server is also still treated as an empty result, preserving the historic contract that a fresh Server can be safely introspected before its daemon is up. Other tmux errors, such as socket permission failures or unsupported flags, now surface.

What's new

• Client object and Server.clients accessor. New typed dataclass for tmux's attached-client model. client_name is the stable identifier; attached_session / attached_window / attached_pane re-read list-clients before resolving. attached_pane follows the attached session's current window — that can differ from the per-client active pane set by select-pane -P.
• Server.display_message and Window.display_message. Server reads like #{version} and #{socket_path} work without a pane handle; window reads (#{window_zoomed_flag}, #{window_active_clients_list}) auto-bind to the window's id. All three display_message wrappers (including the existing Pane.display_message) surface tmux stderr via warnings.warn rather than dropping it silently.
• tmux-native filtering with search_*(). Server.search_panes / search_windows / search_sessions plus the Session and Window analogues take a filter= kwarg routed to tmux's -f flag. tmux evaluates the expression and returns only matching objects. Caveat: tmux silently expands a malformed expression to empty, which it treats as false — a typo looks identical to "no matches".
• Pane.send_keys(cmd=None, …) flag-only invocation. Pass cmd=None together with reset=True or repeat=N to invoke tmux's flag-only send-keys -R / send-keys -N <n> form without any trailing key argument.
• Server.list_buffers(format_string=, filter=). Project a chosen -F template or push a buffer-name match expression through tmux's format engine — same bad-filter caveat as the search_* methods.
• Server.run_shell(cwd=, show_stderr=). New kwargs map to tmux's -c (3.4+) and -E (3.6+) flags. Older tmux warns and ignores the kwarg instead of erroring.
• Pane.capture_pane(pending=True). Return bytes tmux has read from the pane but not yet committed to the terminal — useful for diagnosing programs whose output stalls mid-sequence.
• More format-token fields on tmux objects. Pane / Window / Session / Client expose more typed attributes for pane state (pane_dead, pane_in_mode, pane_marked, pane_synchronized, pane_path, pane_pipe), window state (window_zoomed_flag, window_silence_flag, window_flags), session state (session_marked), and client state (client_session, client_readonly, client_termtype). Tokens the running tmux does not support stay None instead of making the listing fail.

Fixes

• Pane.reset() now clears pane scrollback. In 0.56.0 the history clear silently no-op'd, leaving the scrollback intact (#650).

Documentation

• New API page: libtmux.client.
• New Format-Token Fields topic explains why some fields describe an active child object — for example, session.pane_id reflects the active pane in the session's current window.

What's Changed

• CHANGES(docs): rewrite release history for May 2026 by @tony in #669
• Increase tmux coverage: Client, typed fields, Native filtering by @tony in #672

Full Changelog: v0.56.0...v0.57.0
libtmux on  master [?] ❯ cat release.md
libtmux 0.57.0 broadens tmux support around attached clients, tmux-native filtering, and format-token fields. Client gives callers a typed object for attached terminals, search_*() methods let tmux return only matching sessions, windows, and panes, and more tmux format tokens are exposed as typed attributes. LibTmuxException now records which tmux subcommand failed, making command errors easier to handle downstream.

Full release notes: https://libtmux.git-pull.com/history/#libtmux-0-57-0-2026-05-17

Breaking changes

LibTmuxException string form gains a subcommand prefix

When LibTmuxException is raised from a libtmux method, str(exc) now begins with the originating tmux subcommand name followed by ": ". An error from Session.last_window() used to render as "can't find window" and now renders as "last-window: can't find window".

exc.args[0] still carries the original tmux error text, and the new LibTmuxException.subcommand attribute exposes the tmux subcommand name as a separate field. raise_if_stderr() is the shared helper that populates both.

The error-payload type also changed: exc.args[0] is now str, joined with "\n" when tmux emitted multiple stderr lines. Previously it was list[str]. Code that pattern-matches on str(exc) exactly, anchors a regex with ^ against the old shape, or indexes exc.args[0] element-by-element will no longer match. Substring matches ("can't find" in str(exc)) and unanchored re.search patterns continue to work unchanged.

See the migration guide for the upgrade pattern.

Server.sessions, Server.clients, Server.search_sessions raise on tmux errors

Previously, a tmux command failure under Server.sessions, Server.clients, or Server.search_sessions() could return an empty QueryList indistinguishable from "no sessions / no clients attached" or "filter matched nothing". They now let LibTmuxException propagate for real tmux failures.

Genuine empty results — a server with no attached clients, or a filter that matched zero sessions — still return an empty QueryList. A missing or not-yet-started tmux server is also still treated as an empty result, preserving the historic contract that a fresh Server can be safely introspected before its daemon is up. Other tmux errors, such as socket permission failures or unsupported flags, now surface.

What's new

• Client object and Server.clients accessor. New typed dataclass for tmux's attached-client model. client_name is the stable identifier; attached_session / attached_window / attached_pane re-read list-clients before resolving. attached_pane follows the attached session's current window — that can differ from the per-client active pane set by select-pane -P.
• **Server.display_message and [Window.display_message...

v0.56.0

The tmux command parity release. ~50 new public methods land across Server, Pane, Window, and Session, plus expanded flag coverage on existing wrappers, plus a control_mode test fixture that lets commands requiring an attached client run under CI without a TTY. Net result: callers no longer need to drop down to Server.cmd(...) for the commands tmux ships out of the box.

No breaking changes — public API is purely additive.

Highlights

Interactive tmux commands now scriptable

New wrappers for commands that require an attached client:

• Pane.display_popup, Pane.display_panes
• Pane.choose_buffer, Pane.choose_client, Pane.choose_tree
• Server.display_menu, Server.command_prompt, Server.confirm_before
• Session.detach_client, Server.detach_client, Server.detach_all_clients

The three detach-client wrappers each map to one tmux flag group exactly, with a single subprocess call:

Wrapper	tmux invocation	Scope
Session.detach_client()	tmux detach-client -s <session_id>	every client in this session
Server.detach_client(target_client=...)	tmux detach-client [-t <client>]	server-wide single-client lookup
Server.detach_all_clients(target_client=...)	tmux detach-client -a [-t <keep>]	server-wide, optionally preserving one client

tmux buffer I/O suite

Round-trip pane content through named tmux buffers — useful for clipboard interop and inter-process data hand-off:

• Server.set_buffer, Server.show_buffer, Server.delete_buffer
• Server.save_buffer, Server.load_buffer, Server.list_buffers
• Pane.paste_buffer

Key bindings, shell execution, and client management

• Server: bind_key, unbind_key, list_keys, list_commands, run_shell, if_shell, source_file, list_clients, start_server, lock_server, lock_client, refresh_client, suspend_client, server_access, show_messages, show_prompt_history, clear_prompt_history
• Session: lock_session
• Pane: send_prefix

Window and pane manipulation parity

• Window: swap, link, unlink, respawn, last_pane, next_layout, previous_layout, rotate
• Pane: swap, join, break_pane, move, pipe, clear_history, respawn, copy_mode, clock_mode, customize_mode, find_window
• Server: wait_for
• Session: last_window, next_window, previous_window

Filled-in flag coverage on existing methods

Most pre-existing wrappers now expose the remaining tmux flags:

• Pane.send_keys — literal, hex_keys, key_name, expand_formats, target_client, repeat, reset, copy_mode_cmd
• Pane.split — percentage=
• Pane.capture_pane — alternate_screen, quiet, mode_screen, to_buffer (writes capture into a tmux buffer instead of returning it)
• <a href="https://libt...

v0.55.1 - improved docs, pytest teardown

A point release focused on a pytest-plugin cleanup fix, a new Sphinx extension for documenting pytest fixtures, and a docs-stack migration to gp-sphinx.

Highlights

Fix: pytest_plugin leaks tmux socket files on teardown (#661, fixes #660)

The server and TestServer fixtures now unlink(2) the tmux socket from /tmp/tmux-<uid>/ during teardown, in addition to calling server.kill(). tmux does not reliably remove its own socket on non-graceful exit, so /tmp/tmux-<uid>/ would accumulate stale libtmux_test* entries across runs — 10k+ observed on long-lived dev machines.

A new internal _reap_test_server helper centralizes the kill + unlink flow and suppresses cleanup-time errors, so a finalizer failure can no longer mask the real test failure.

If you use libtmux's pytest plugin in CI or locally, upgrade to stop the leak.

New: Sphinx extension for pytest fixture documentation (#656)

A new Sphinx extension (docs/_ext/sphinx_pytest_fixtures.py) renders pytest fixtures as first-class API documentation with scope/kind/factory badges, cross-referenced dependencies, and auto-generated usage snippets.

• .. autofixture:: — autodoc-style documenter for individual fixtures
• .. autofixtures:: — bulk discovery and rendering from a module
• .. autofixture-index:: — auto-generated index table with linked return types (via intersphinx) and parsed RST descriptions
• :fixture: cross-reference role with short-name resolution
• Scope, kind, and autouse badges with touch-accessible tooltips
• Responsive layout (mobile metadata stacking, badge font scaling, scroll wrappers)
• WCAG AA contrast compliance in both light and dark mode
• 109 tests (unit + integration)

Also fixes an inaccurate session_params fixture docstring surfaced by the new extension.

Documentation

• Docs restructured to the Library Skeleton pattern (#652)
• Self-hosted fonts, eliminated layout shift, added SPA-style navigation (#643)
• Standardized shell code-block formatting across all docs (#644)
• Migrated the docs stack to gp-sphinx workspace packages (#657)
• Visual improvements to API docs via gp-sphinx (#658)
• Bumped gp-sphinx to v0.0.1a8 (#659); subsequent bump to v0.0.1a9 on master

Development

• Added types-docutils to dev dependencies for mypy type checking (#656)

What's Changed

• docs: self-host fonts, eliminate layout shift, add SPA navigation by @tony in #643
• docs(style[shell]): Standardize shell code blocks by @tony in #644
• docs(redesign): restructure documentation to Library Skeleton pattern by @tony in #652
• feat(_ext[sphinx_pytest_fixtures]): Sphinx extension for pytest fixture documentation by @tony in #656
• docs: Migrate to gp-sphinx workspace packages by @tony in #657
• docs(feat[api-style]): Visual improvements to API docs via gp-sphinx by @tony in #658
• chore(docs): adopt gp-sphinx v0.0.1a8 by @tony in #659
• fix(pytest_plugin): unlink socket file on fixture teardown by @tony in #661

Full Changelog: v0.55.0...v0.55.1

v0.55.0 - compatibility features, more logging

What's Changed

via @tony in #636

Pane.set_title()

New Pane.set_title() method wraps select-pane -T and returns the pane
for method chaining. A Pane.title property aliases pane_title for
convenience:

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 pane format
queries (it was previously excluded via an incorrect "removed in 3.1+" comment).

Configurable tmux binary path

Server now accepts a tmux_bin parameter to use an alternative binary
(e.g. wemux, byobu, or a custom build):

server = Server(socket_name="myserver", tmux_bin="/usr/local/bin/tmux-next")

The path is threaded through Server.cmd(), Server.raise_if_dead(),
fetch_objs(), all version-check functions (has_version,
has_gte_version, etc.), and hook scope guards in HooksMixin. Child
objects (Session, Window, Pane) inherit it automatically. Falls back to
shutil.which("tmux") when not set.

Pre-execution command logging

tmux_cmd now emits a structured DEBUG log record with
extra={"tmux_cmd": ...} before invoking the subprocess, using
shlex.join for POSIX-correct quoting. This complements the existing
post-execution stdout log and is a prerequisite for a future dry-run mode.

Bug fix: TmuxCommandNotFound raised for invalid tmux_bin path

Passing a non-existent binary path previously surfaced as a raw
FileNotFoundError from subprocess. Both tmux_cmd and
raise_if_dead now catch FileNotFoundError and raise
TmuxCommandNotFound consistently.

Full Changelog: v0.54.0...v0.55.