## 🐍 What is libtmux?
libtmux is a typed Python API over [tmux], the terminal multiplexer. Stop shelling out and parsing `tmux ls`. Instead, interact with real Python objects: `Server`, `Session`, `Window`, and `Pane`. The same API powers [tmuxp], so it stays battle-tested in real-world workflows.
### ✨ Features
- Typed, object-oriented control of tmux state
- Query and [traverse](https://libtmux.git-pull.com/topics/traversal/) live sessions, windows, and panes
- Raw escape hatch via `.cmd(...)` on any object
- Works with multiple tmux sockets and servers
- [Context managers](https://libtmux.git-pull.com/topics/context_managers/) for automatic cleanup
- [pytest plugin](https://libtmux.git-pull.com/api/pytest-plugin/) for isolated tmux fixtures
- Proven in production via tmuxp and other tooling
## Requirements & support
- tmux: >= 3.2a
- Python: >= 3.10 (CPython and PyPy)
Maintenance-only backports (no new fixes):
- Python 2.x: [`v0.8.x`](https://github.com/tmux-python/libtmux/tree/v0.8.x)
- tmux 1.8-3.1c: [`v0.48.x`](https://github.com/tmux-python/libtmux/tree/v0.48.x)
## 📦 Installation
Stable release:
```console
$ pip install libtmux
```
With pipx:
```console
$ pipx install libtmux
```
With uv / uvx:
```console
$ uv add libtmux
```
```console
$ uvx --from "libtmux" python
```
From the main branch (bleeding edge):
```console
$ pip install 'git+https://github.com/tmux-python/libtmux.git'
```
Tip: libtmux is pre-1.0. Pin a range in projects to avoid surprises:
requirements.txt:
```ini
libtmux==0.50.*
```
pyproject.toml:
```toml
libtmux = "0.50.*"
```
## 🚀 Quickstart
### Open a tmux session
First, start a tmux session to connect to:
```console
$ tmux new-session -s foo -n bar
```
### Pilot your tmux session via Python
Use [ptpython], [ipython], etc. for a nice REPL with autocompletions:
```console
$ pip install --user ptpython
```
```console
$ ptpython
```
Connect to a live tmux session:
```python
>>> import libtmux
>>> svr = libtmux.Server()
>>> svr
Server(socket_path=/tmp/tmux-.../default)
```
**Tip:** You can also use [tmuxp]'s [`tmuxp shell`] to drop straight into your
current tmux server / session / window / pane.
[ptpython]: https://github.com/prompt-toolkit/ptpython
[ipython]: https://ipython.org/
[`tmuxp shell`]: https://tmuxp.git-pull.com/cli/shell/
### Run any tmux command
Every object has a `.cmd()` escape hatch that honors socket name and path:
```python
>>> server = Server(socket_name='libtmux_doctest')
>>> server.cmd('display-message', 'hello world')
