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
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¶

import libtmux

server = libtmux.Server()
session = server.sessions.get(session_name="my-project")
window = session.active_window
pane = window.split()
pane.send_keys("echo hello")

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:

def test_my_tool(session):
    window = session.new_window(window_name="test")
    pane = window.active_pane
    pane.send_keys("echo hello")
    assert window.window_name == "test"