(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 {ref}tmuxp load <cli-load> builds the session and drops you into it. This page takes you from nothing to a running session.

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 {ref}completion.

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

:::{seealso}

{ref}examples, {ref}commands, {ref}completion.

:::

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:

:language: yaml

$ 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.

:::{seealso}

{ref}libtmux python API documentation <libtmux:api> and {ref}developing.

:::

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: