tmuxp is usable but still needs your help reporting errors, bugs and usability feedback. If you encounter an error, please post on the Issue tracker.



Assure you have at least tmux >= 1.8 and python >= 2.6. For Ubuntu 12.04/12.10/13.04 users, you can download the tmux 1.8 package for Ubuntu 13.10 from and install it using dpkg.

$ pip install tmuxp

You can upgrade to the latest release with:

$ pip install tmuxp -U

Then install Bash completion.

Known issue on RHEL/CentOS/Fedora

For all RedHat-based distros there might be an issue with starting tmuxp.

$ tmuxp Traceback (most recent call last):

File “/usr/bin/tmuxp”, line 5, in <module>
from pkg_resources import load_entry_point
File “/usr/lib/python2.6/site-packages/”, line 2655, in <module>
File “/usr/lib/python2.6/site-packages/”, line 648, in require
needed = self.resolve(parse_requirements(requirements))
File “/usr/lib/python2.6/site-packages/”, line 546, in resolve
raise DistributionNotFound(req)

pkg_resources.DistributionNotFound: argparse

Try upgrading setuptools, has been proven to solve the problem on Fedora 22, CentOS 7 and RHEL 6.

sudo pip install -U setuptools

Can be tested in the Python REPL like this.

>>> import pkg_resources
>>> pkg_resources.get_distribution('argparse')
argparse 1.3.0 (/usr/lib/python2.6/site-packages)

The above operation would give the same exception (DistributionNotFound) before setuptools was upgraded.


tmuxp launches workspaces / sessions from JSON and YAML files.

Configuration files can be stored in $HOME/.tmuxp or in project directories as, .tmuxp.json or .tmuxp.yaml.

Every configuration is required to have:

  1. session_name
  2. list of windows
  3. list of panes for every window in windows

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

session_name: 2-pane-vertical
  - window_name: my test window
      - pwd
      - pwd
$ tmuxp load example.yaml

This creates your tmuxp session.


ORM - Object Relational Mapper

AL - Abstraction Layer

python abstraction layer

tmuxp python api tmux(1) equivalent
Server.new_session() $ tmux new-session
Server.list_sessions() $ tmux list-sessions
Session.list_windows() $ tmux list-windows
Session.new_window() $ tmux new-window
Window.list_panes() $ tmux list-panes
Window.split_window() $ tmux split-window
Pane.send_keys() $ tmux send-keys

tmux ORM

tmuxp’s core internal feature is the object relation and orchestration of the tmux server (think an engine in SQLAlchemy) and the server’s sessions, so on...

instances of tmux objects use tmux 1.8‘s pane_id, window_id and session_id to build create python objects to build workspaces with the freshest data.