libtmux

library0.62.0pypypi✓ verified 24d ago

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.

devops

pip install libtmux

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · LIBTMUX

libtmux

devopspythonv0.62.0

Install

1.7s avg

Import

238ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.62.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.252s · 18.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.224s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Server

✓ from libtmux import Server

Session

✓ from libtmux import Session

Window

✓ from libtmux import Window

Pane

✓ from libtmux import Pane

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()

Debug

Known issues

breakingAs 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.

affects: >=0.51.0

breakinglibtmux 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`.

affects: >=0.49.0

breakingIn 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.

affects: >=0.53.0

gotchalibtmux 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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'libtmux'

The 'libtmux' Python package is not installed in the Python environment where the script is being executed.

fix

Install the library using pip: `pip install libtmux`

libtmux.exc.TmuxCommandNotFound: Application binary for tmux not found.

The 'tmux' command-line utility, which libtmux wraps, is not installed on your system or is not present in the system's PATH.

fix

Install tmux on your operating system (e.g., `sudo apt-get install tmux` on Debian/Ubuntu, `brew install tmux` on macOS).

failed to connect to server

The libtmux library could not connect to a running tmux server, either because no server is active or the tmux socket file is invalid/inaccessible.

fix

Ensure a tmux server is running by manually starting a session (e.g., `tmux new -s my_session`) before executing the Python script. If the error persists, check for and remove stale tmux socket files, typically found in `/tmp/tmux-*`.

libtmux.exc.TmuxObjectDoesNotExist: Session does not exist in the server.

The script attempted to access a tmux object (session, window, or pane) using an identifier (ID or name) that does not correspond to an existing object on the current tmux server, or the locale settings are incorrect.

fix

Verify the target session, window, or pane exists (e.g., using `tmux ls` or by inspecting `server.sessions`). Ensure the libtmux objects are refreshed to reflect the current tmux state (e.g., `server.sessions.refresh()`). For locale issues, set the `LANG` environment variable correctly (e.g., `export LANG=en_US.UTF-8`).

libtmux.exc.LibTmuxException: (['no space for new pane'])

When trying to create or split a pane, the tmux server reported that there is insufficient screen space to accommodate a new pane with the current window dimensions and layout. This often occurs in headless environments or with small default terminal sizes.

fix

Ensure the tmux session is attached to a client with adequate screen dimensions. Alternatively, configure tmux with larger default window/pane sizes, or use libtmux methods to explicitly set pane/window sizes and layouts (e.g., `window.select_layout('even-horizontal')`) after splitting.

Upgrade

Version history

0.62.0latest on PyPI · released Jul 12, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/tmux-python/libtmux ↗

packagehttps://pypi.org/project/libtmux/ ↗

docshttps://libtmux.git-pull.com ↗

changeloghttps://github.com/tmux-python/libtmux/blob/master/CHANGES ↗