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

pytest plugin and test helpers for isolated tmux environments.

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¶

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"