libtmux Files

Highlights

• Structured lifecycle logging across Server, Session, Window, and Pane with filterable extra context
• Bug fixes for rename_window(), Server.kill(), new_session(), and kill_window() error handling

---

What's new

Structured lifecycle logging (#637)

All lifecycle operations (create, kill, rename, split) now emit INFO-level log records with structured extra context. Every log call includes scalar keys for filtering in log aggregators and test assertions via caplog.records:

Key	Type	Context
tmux_subcommand	str	tmux subcommand (e.g. new-session)
tmux_target	str	tmux target specifier
tmux_session	str	session name
tmux_window	str	window name or index
tmux_pane	str	pane identifier

Logging hygiene improvements:

• NullHandler added to library __init__.py per Python logging best practices
• DEBUG-level structured logs for tmux_cmd execution with isEnabledFor guards and heavy keys (tmux_stdout, tmux_stderr, tmux_stdout_len, tmux_stderr_len)
• Lazy formatting: replaced f-string log formatting with %s throughout
• Diagnostics: replaced traceback.print_stack() with logger.debug(exc_info=True)
• Options warnings: replaced logger.exception() with logger.warning() and tmux_option_key structured context for recoverable parse failures
• Cleanup: removed unused logger definitions from modules that don't log

---

Bug fixes

Window.rename_window() now raises on failure (#637)

Previously rename_window() caught all exceptions and logged them, masking tmux errors. It now propagates the error, consistent with all other command methods.

Server.kill() captures stderr (#637)

Server.kill() previously discarded the tmux return value. It now checks stderr, raises on unexpected errors, and silently returns for expected conditions ("no server running", "error connecting to").

Server.new_session() checks kill-session stderr (#637)

When kill_session=True and the existing session kill fails, new_session() now raises LibTmuxException with the stderr instead of proceeding silently.

Session.kill_window() target formatting fix (#637)

Fixed self.window_name (wrong attribute) to self.session_name when formatting tmux targets for integer target_window values. Also widened the type signature from str | None to str | int | None to match the existing isinstance(target_window, int) branch.

---

Installation

pip:

:::console
$ pip install libtmux==0.54.0

uv:

:::console
$ uv add libtmux==0.54.0

---

What's Changed

• Add structured logging with lifecycle events and test coverage by @tony in https://github.com/tmux-python/libtmux/pull/637

Full Changelog: https://github.com/tmux-python/libtmux/compare/v0.53.1...v0.54.0