tmuxp

1.67.0 · active · verified Thu Apr 16

tmuxp is an active and frequently updated Python session manager for tmux, enabling users to save, load, and manage complex tmux sessions and workspaces via simple YAML or JSON configuration files. It is built upon the `libtmux` Python API for programmatic interaction with tmux.

Common errors

```
tmuxp: error: unrecognized arguments: <second_config_file>
```
cause In older versions (prior to 1.17.2), `tmuxp load` did not correctly handle multiple configuration files passed as separate arguments.

fix Upgrade tmuxp to version 1.17.2 or newer, which fixed the issue. Alternatively, load each session individually or specify a directory containing multiple `.tmuxp.yaml` files.
```
OSError: [Errno 13] Permission denied
```
cause This usually indicates issues with Python's PATH configuration or incorrect use of `sudo` when installing or running `tmuxp`.

fix Ensure `tmuxp` is installed correctly for your user (e.g., `pip install --user tmuxp`) and that your PATH is configured to find user-installed scripts. Avoid using `sudo` with `pip install --user`.
```
Commands in panes not executing after OS upgrade or script changes.
```
cause Often related to changes in shell environment, PATH, or system Python setup after an OS upgrade. Sometimes, `shell_command_before` or `shell_command` might have changed behavior or dependencies.

fix Check your system's Python setup (`which python`, `which pip`), ensure correct virtual environment activation within `tmuxp` configs, and verify shell command execution outside `tmuxp`. Use `tmuxp debug-info` for system details.
```
TmuxObjectDoesNotExist traceback when detaching from a killed session.
```
cause A bug in earlier versions of `libtmux` (prior to 0.53.0) caused this traceback when a `tmuxp` session was killed.

fix Upgrade `libtmux` to version 0.53.0 or newer. This fix was included in `tmuxp` v1.62.0.

Warnings

breaking Python 3.9 support was dropped with tmuxp v1.56.0. The minimum required Python version is now 3.10.
Fix: Upgrade your Python environment to 3.10 or newer.
breaking The minimum required `libtmux` version frequently bumps. Ensure `libtmux` is kept up-to-date, or pin a compatible range in your `pyproject.toml` or `requirements.txt`.
Fix: Run `pip install --upgrade libtmux` or update your `libtmux` dependency specification.
gotcha `tmuxp load` now displays a real-time animated progress spinner, replacing the static `[Loading]` message. This may affect scripts parsing `tmuxp load` output.
Fix: Adjust scripts to account for the new spinner output, or disable it using `--no-progress`. You can also customize the spinner with `--progress-format` and `--progress-lines`.
gotcha Default CLI log level changed from INFO to WARNING, suppressing raw Python tracebacks on workspace build failure. Detailed error information is now available via `--log-level debug`.
Fix: For detailed debugging output, add `--log-level debug` to your `tmuxp` command.
deprecated tmux versions below 3.2a are deprecated (via libtmux v0.48.0). A `FutureWarning` will be emitted on first use, with support for these versions being removed in a future release.
Fix: Upgrade your tmux installation to version 3.2a or newer. You can suppress the warning by setting the `LIBTMUX_SUPPRESS_VERSION_WARNING=1` environment variable.

Install

pip install tmuxp Install stable version

Imports

Server
```
from libtmux import Server
```
tmuxp is primarily a CLI tool. For programmatic interaction, it relies on libtmux. The 'tmuxp shell' command can drop you into a Python console with libtmux objects preloaded.
Session
```
from libtmux import Session
```
Part of the libtmux API for managing tmux sessions programmatically.

Quickstart

Create a YAML configuration file to define a tmux session, then load it using the `tmuxp load` CLI command. Configuration files are typically stored in `~/.tmuxp/` or within project directories (e.g., `.tmuxp.yaml`).

import os

# Create a sample tmuxp configuration file
config_content = """
session_name: my_dev_session
windows:
  - window_name: dev
    layout: main-vertical
    panes:
      - shell_command: echo 'Hello from pane 1!'
      - shell_command: echo 'Hello from pane 2!'
  - window_name: logs
    panes:
      - shell_command: tail -f /var/log/syslog
"""

config_dir = os.path.expanduser("~/.tmuxp")
os.makedirs(config_dir, exist_ok=True)
config_path = os.path.join(config_dir, "my_dev_session.yaml")

with open(config_path, "w") as f:
    f.write(config_content)

print(f"Config saved to: {config_path}")
print("To load this session, run: tmuxp load my_dev_session")
print("Or, from the directory containing the file: tmuxp load ./my_dev_session.yaml")

view raw JSON →