libtmux¶

Typed Python API for tmux. Control servers, sessions, windows, and panes as Python objects.

Quickstart

Install and make your first API call in 5 minutes.

Quickstart
Topics

Architecture, traversal, filtering, and automation patterns.

Topics
API Reference

Every public class, function, and exception.

API Reference
Testing

Isolated tmux fixtures and test helpers.

Testing Utilities
Contributing

Development setup, code style, release process.

Project

Install¶

$ pip install libtmux

$ uv add libtmux

Tip: libtmux is pre-1.0. Pin to a range: libtmux>=0.55,<0.56

See Quickstart for all methods and first steps.

At a glance¶

>>> demo_window = session.new_window(window_name="my-project")
>>> demo_pane = demo_window.active_pane
>>> demo_pane.send_keys("echo hello")
>>> demo_window.kill()

Server  →  Session  →  Window  →  Pane

Every level of the tmux hierarchy is a typed Python object with traversal, filtering, and command execution.

Object

What it wraps

Server

tmux server / socket

Session

tmux session

Window

tmux window

Pane

tmux pane

Testing¶

libtmux ships a pytest plugin with isolated tmux fixtures:

>>> test_window = session.new_window(window_name="test")
>>> test_pane = test_window.active_pane
>>> test_pane.send_keys("echo hello")
>>> test_window.window_name
'test'
>>> test_window.kill()