libtmux

0.55.0 · active · verified Thu Apr 09

libtmux is a typed Python library providing an ORM (Object-Relational Mapper) wrapper for tmux, the terminal multiplexer. It allows programmatic control over tmux servers, sessions, windows, and panes. The current version is 0.55.0, and it maintains an active release cadence with frequent updates and bug fixes.

Warnings

breaking As of v0.51.0, legacy API methods (deprecated in v0.16–v0.33) now raise `DeprecatedError` instead of just emitting a `DeprecationWarning`. This will cause hard errors if old methods are still in use.
Fix: Consult the libtmux migration guide (https://libtmux.git-pull.com/migration.html) and update your code to use the modern, recommended API methods.
breaking libtmux versions 0.49.0 and newer have dropped support for tmux versions older than 3.2. If you are running an older tmux version, operations may fail or behave unexpectedly.
Fix: Upgrade your tmux installation to version 3.2 or newer to ensure compatibility. Check your tmux version with `tmux -V`.
breaking In v0.53.0, the `Session.attach()` method no longer automatically calls `refresh()` after returning. If your application expects immediate state updates after attaching, you will need to explicitly call `session.refresh()`.
Fix: If your workflow requires the session object to reflect the latest state immediately after `attach()`, manually call `session.refresh()` after `session.attach()` returns.
gotcha libtmux requires Python 3.10 or newer, but less than Python 4.0. Running on older Python versions (e.g., 3.9) will result in installation or runtime errors.
Fix: Ensure your Python environment is version 3.10, 3.11, or 3.12. Upgrade your Python installation if necessary.

Install

pip install libtmux Install libtmux

Imports

Server
```
from libtmux import Server
```
Session
```
from libtmux import Session
```
Window
```
from libtmux import Window
```
Pane
```
from libtmux import Pane
```

Quickstart

Demonstrates connecting to the tmux server, finding or creating a session, accessing its attached window and pane, and sending commands to the pane. The example includes optional session cleanup.

from libtmux import Server

# Connect to the tmux server
server = Server()

# Find or create a session named 'my_session'
session = server.find_where({"session_name": "my_session"})
if session is None:
    session = server.new_session(session_name="my_session")

# Get the attached window and pane
window = session.attached_window
pane = window.attached_pane

# Send keys to the pane
pane.send_keys("echo Hello, libtmux!", enter=True)

# Print current session name
print(f"Active session: {session.name}")

# Kill the session (optional, for cleanup)
# session.kill_session()

view raw JSON →