Quickstart

tmuxp launches a whole tmux workspace — its windows, panes, and the commands inside them — from a single YAML or JSON file. Install it, write one file, and tmuxp load builds the session and drops you into it. This page takes you from nothing to a running session.

Installation

Ensure you have at least tmux >= 3.2 and python >= 3.10.

$ pip install --user tmuxp

If you manage dependencies with uv inside a project environment, add tmuxp to your lockfile instead:

$ uv add tmuxp

To run tmuxp without installing it globally — the way you’d use pipx — invoke it through uvx:

$ uvx tmuxp

Upgrade to the latest release with:

$ pip install --user --upgrade tmuxp

Within a uv-managed project, upgrade by refreshing the lockfile and syncing:

$ uv lock --upgrade-package tmuxp

$ uv sync

Then install Completions.

Homebrew users can install it with:

$ brew install tmuxp

Developmental releases

New versions of tmuxp are published to PyPI as alpha, beta, or release candidates. Their version carries an a1, b1, or rc1 suffix — 1.10.0b4 is the fourth beta of 1.10.0, before general availability.

Install the latest pre-release with the tool you use:

$ pip install --user --upgrade --pre tmuxp

$ uv add tmuxp --prerelease allow

$ uvx --from 'tmuxp' --prerelease allow tmuxp

$ pipx install --suffix=@next 'tmuxp' --pip-args '\--pre' --force

After the pipx install, load with tmuxp@next load [session].

Or track trunk directly (it can break):

$ pip install --user -e git+https://github.com/tmux-python/tmuxp.git#egg=tmuxp

$ uv add "tmuxp @ git+https://github.com/tmux-python/tmuxp.git@master"

$ uvx --from "tmuxp @ git+https://github.com/tmux-python/tmuxp.git@master" tmuxp

$ pipx install --suffix=@master 'tmuxp @ git+https://github.com/tmux-python/tmuxp.git@master' --force

Commands

See also

Examples, CLI Reference, Completions.

tmuxp launches workspaces / sessions from JSON and YAML files.

Workspace files live in $HOME/.tmuxp, or in a project directory as .tmuxp.yaml, .tmuxp.yml, or .tmuxp.json. Every workspace file needs:

1. a session_name

2. a list of windows

3. a list of panes for every window

Create a file, ~/.tmuxp/example.yaml:

session_name: 2-pane-vertical
windows:
  - window_name: my test window
    panes:
      - echo hello
      - echo hello

$ tmuxp load example.yaml

This builds and attaches your session.

Load several at once:

$ tmuxp load example.yaml anothersession.yaml

If you’re already inside a session, tmuxp offers to switch-client for you, or to append the new windows to the session you’re in.

You can point tmuxp at a different config directory with the TMUXP_CONFIGDIR environment variable:

$ TMUXP_CONFIGDIR=$HOME/.tmuxpmoo tmuxp load cpython

Or set it in your ~/.bashrc / ~/.zshrc:

$ export TMUXP_CONFIGDIR=$HOME/.yourconfigdir/tmuxp

You can also import configs from teamocil and tmuxinator.

Pythonics

See also

libtmux python API documentation and Developing and Testing.

Under the hood, tmuxp drives tmux through libtmux — an object-relational mapper and abstraction layer over tmux(1)’s commands. Each config concept maps to a libtmux call:

libtmux Python API	tmux(1) equivalent
libtmux.Server.new_session()	$ tmux new-session
libtmux.Server.sessions	$ tmux list-sessions
libtmux.Session.windows	$ tmux list-windows
libtmux.Session.new_window()	$ tmux new-window
libtmux.Window.panes	$ tmux list-panes
libtmux.Window.split()	$ tmux split-window
libtmux.Pane.send_keys()	$ tmux send-keys