{"id":8717,"library":"tmuxp","title":"tmuxp","description":"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.","status":"active","version":"1.67.0","language":"en","source_language":"en","source_url":"https://github.com/tmux-python/tmuxp","tags":["tmux","session management","cli","terminal","productivity","workflow"],"install":[{"cmd":"pip install tmuxp","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Terminal multiplexer that tmuxp manages; requires tmux >= 3.2a.","package":"tmux","optional":false},{"reason":"Core Python API for tmux, upon which tmuxp is built; requires libtmux ~=0.55.0 (or newer, pinned to 0.50.* for projects).","package":"libtmux","optional":false},{"reason":"Required for parsing YAML configuration files.","package":"PyYAML","optional":false},{"reason":"Provides semantic color output for the CLI.","package":"colorama","optional":false}],"imports":[{"note":"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.","symbol":"Server","correct":"from libtmux import Server"},{"note":"Part of the libtmux API for managing tmux sessions programmatically.","symbol":"Session","correct":"from libtmux import Session"}],"quickstart":{"code":"import os\n\n# Create a sample tmuxp configuration file\nconfig_content = \"\"\"\nsession_name: my_dev_session\nwindows:\n  - window_name: dev\n    layout: main-vertical\n    panes:\n      - shell_command: echo 'Hello from pane 1!'\n      - shell_command: echo 'Hello from pane 2!'\n  - window_name: logs\n    panes:\n      - shell_command: tail -f /var/log/syslog\n\"\"\"\n\nconfig_dir = os.path.expanduser(\"~/.tmuxp\")\nos.makedirs(config_dir, exist_ok=True)\nconfig_path = os.path.join(config_dir, \"my_dev_session.yaml\")\n\nwith open(config_path, \"w\") as f:\n    f.write(config_content)\n\nprint(f\"Config saved to: {config_path}\")\nprint(\"To load this session, run: tmuxp load my_dev_session\")\nprint(\"Or, from the directory containing the file: tmuxp load ./my_dev_session.yaml\")","lang":"python","description":"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`)."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer.","message":"Python 3.9 support was dropped with tmuxp v1.56.0. The minimum required Python version is now 3.10.","severity":"breaking","affected_versions":">=1.56.0"},{"fix":"Run `pip install --upgrade libtmux` or update your `libtmux` dependency specification.","message":"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`.","severity":"breaking","affected_versions":"All versions"},{"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`.","message":"`tmuxp load` now displays a real-time animated progress spinner, replacing the static `[Loading]` message. This may affect scripts parsing `tmuxp load` output.","severity":"gotcha","affected_versions":">=1.67.0"},{"fix":"For detailed debugging output, add `--log-level debug` to your `tmuxp` command.","message":"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`.","severity":"gotcha","affected_versions":">=1.66.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"All versions with libtmux >= 0.48.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"In older versions (prior to 1.17.2), `tmuxp load` did not correctly handle multiple configuration files passed as separate arguments.","error":"tmuxp: error: unrecognized arguments: <second_config_file>"},{"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`.","cause":"This usually indicates issues with Python's PATH configuration or incorrect use of `sudo` when installing or running `tmuxp`.","error":"OSError: [Errno 13] Permission denied"},{"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.","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.","error":"Commands in panes not executing after OS upgrade or script changes."},{"fix":"Upgrade `libtmux` to version 0.53.0 or newer. This fix was included in `tmuxp` v1.62.0.","cause":"A bug in earlier versions of `libtmux` (prior to 0.53.0) caused this traceback when a `tmuxp` session was killed.","error":"TmuxObjectDoesNotExist traceback when detaching from a killed session."}]}