---
id: libtmux
version: "0.62.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# libtmux — Typed library that provides an ORM wrapper for tmux, a terminal multiplexer.

License: permissive · Maintenance: active · Downloads: 13.1M/mo

## What it is and what it does

libtmux is a typed Python wrapper around tmux that replaces shell command parsing with real object-oriented control. Instead of running `tmux ls` and parsing output, you work with `Server`, `Session`, `Window`, and `Pane` objects that reflect live tmux state. The library supports querying and filtering collections, traversing the hierarchy (pane → window → session), sending keystrokes to panes, and capturing output—all with full type hints.

The package is battle-tested in production through tmuxp (a declarative workspace manager built on top of it) and includes a pytest plugin for writing isolated tmux tests. It also supports context managers for cleanup, multiple tmux sockets, and a `.cmd()` escape hatch for raw tmux commands when needed. Code running inside a tmux pane can use `from_env()` to locate itself in the hierarchy.

Use it for:

- Automate tmux session setup and teardown in deployment or development scripts without shell parsing.
- Write pytest tests for tools that interact with tmux, using isolated fixtures for each test.
- Build terminal UI tools or dashboards that need to query and control live tmux state programmatically.
- Capture pane output and send commands to tmux from Python applications or background agents.
- Implement tmux-based workflow orchestration (e.g., spawning parallel tasks in separate panes).

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

libtmux provides a typed Python API to control tmux (the terminal multiplexer) programmatically, letting you manage servers, sessions, windows, and panes as Python objects instead of parsing shell commands.

Yes. libtmux is actively maintained, has no external dependencies, supports current Python versions (3.10–3.14, PyPy), and solves a real problem for anyone automating tmux or testing tmux-aware tools. The MIT license imposes no restrictions. Start with a pinned version range (e.g., `libtmux==0.62.*`) since the package is pre-1.0.

## Install

pip install libtmux
uv add libtmux
poetry add libtmux

## Installing libtmux

Before you install: Low friction: pure Python wheel with no runtime dependencies. Active maintenance (last commit 2026-08-13, release 33 days ago). Requires tmux >= 3.2a and Python >= 3.10; older versions available on maintenance branches for Python 2.x and tmux 1.8–3.1c.

License in practice: MIT license (permissive). No restrictions on commercial or proprietary use; attribution appreciated but not required.

Quickstart:

pip install libtmux

import libtmux
server = libtmux.Server()
session = server.sessions.get(session_name="my-session")
window = session.new_window(window_name="work")
pane = window.active_pane
pane.send_keys("echo hello", enter=True)

tmux >= 3.2a must be installed on the system; Python >= 3.10 required.

Verify before relying:

- Whether the pytest plugin is automatically available or requires separate installation.
- Performance characteristics when managing many sessions/windows/panes concurrently.
- Compatibility with tmux forks or non-standard tmux builds.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 13.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

tmux python api, terminal multiplexer control, programmatic tmux automation, session window pane management, tmux object-oriented wrapper, typed tmux library, tmux testing fixtures, terminal-automation, testing-fixtures, typed-api

[View on SkillFed](https://skillfed.io/packages/libtmux) · [View on PyPI](https://pypi.org/project/libtmux/)