Registry / devops / tmuxp
library1.70.0pypypi✓ verified 87d ago

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.

pip install tmuxp
INSTALL
IMPORT
SIG · TMUXP
T
tmuxp
devopspythonv1.70.0
Install
1.9s avg
Import
219ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.70.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.103.920 runs
installs and imports cleanly · install 0.0s · import 0.234s · 21.8MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.9s · import 0.203s · 23MB
20MB installed
● package 20MB
Code
Verified usage

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

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.

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")
tmuxp --version
Debug
Known issues
breakingPython 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.
affects: >=1.56.0
breakingThe 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.
affects: All versions
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`.
affects: >=1.67.0
gotchaDefault 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.
affects: >=1.66.0
deprecatedtmux 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.
affects: All versions with libtmux >= 0.48.0
Errors
Common errors & fixes
tmuxp: error: unrecognized arguments: <second_config_file>
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
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.
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.
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.
Upgrade
Version history
1.70.0latest on PyPI · released May 23, 2026
Audit
Dependencies
tmuxrequiredTerminal multiplexer that tmuxp manages; requires tmux >= 3.2a.
libtmuxrequiredCore Python API for tmux, upon which tmuxp is built; requires libtmux ~=0.55.0 (or newer, pinned to 0.50.* for projects).
PyYAMLrequiredRequired for parsing YAML configuration files.
coloramarequiredProvides semantic color output for the CLI.
Agent activity
17 hits · last 30 days
node
14
OpenAI (training)
1
Resources
tmuxp — pip install tmuxp · libregistry