Here you can find the recent changes to tmuxp.


  • [cli] Load multiple tmux sessions at once, thanks @madprog, #135.
  • [docs] README and Documentation fixes #133 #131.


  • [internal] switch to .venv for virtualenv directory to not conflict with .env (used by autoenv).
  • [internal] move to entr(1) for file watching in tests. update docs.
  • [compatibility] Support Anaconda Python 2 and 3, see #130.


  • [internal] Update to support tmux 2.1 via #122, thank you @estin.
  • [internal] use travis container infrastructure for faster tests
  • [tests] change test in workspace builder test to use top(1) instead of man(1). man(1) caused errors on some systems where PAGER is set.


  • [packaging] Add fix python 3 for sysutils/pytmuxp on FreeBSD ports. See #119 GH and #201564 @ FreeBSD Bugzilla. Thanks Ruslan Makhmatkhanov.


  • [internal]: Renamed config.expandpath to config.expandshell.
  • [internal] [tests]: compat 2.7/3.3 wrapper for EnvironmentVarGuard for testing.
  • [shell_command_before]: You can now use environment variables inside of start_directory, before_script, shell_command_before, session_name and window_name.
  • [docs] [examples]: add example for environmental variables, examples/env-variables.json and examples/env-variables.yaml.
  • [internal] de-vendorize colorama. Thanks @marbu. #110
  • [tests] fix failure of test_pane_order on fedora machines #109 from @marbu
  • [manuals]: append .txt extension to manuals (repo ony) #105 from @yegortimoshenko.
  • [internal] Fix Server.attached_sessions return type #107 by @thomasballinger.
  • [internal]: update travis to use new tmux git repository.


  • [internal] [testing]: fix sniffer test runner in python 3
  • [docs] new animated image demo for RTD and README



  • [internal] Remove package_metadata.py in favor of __about__.py.
  • [docs] scent.py for building docs
  • [docs] docutils from 0.11 to 0.12
  • [internal] bootstrap_env.py will check for linux, darwin (OS X) and windows and install the correct sniffer file watcher plugin.
  • [tests] testsuite for cli uses tempfile.mkdtemp() instead TMP_DIR (which resolved to .tmuxp in the testsuite directory.
  • [tests] replace watchingtestrunner with sniffer in examples. .tmuxp.conf and .tmux.json updated
  • [docs] updates to doc links
  • [docs] make checkbuild for verifying internal / intersphinx doc references.
  • [internal] Add Warning tmux versions less than 1.4 from @techtonik.
  • [internal] [docs] Add documentation on leading space in send_keys from @thomasballinger.
  • [docs] Update about page from teamocil and erb support from @raine.


  • [config] config.expand() now resolves directories in configuration via os.path.expanduser() and os.path.expandvars().

  • [config] config.expandpath() for helping resolve paths.

  • [builder] [cli] improved support for loading tmuxp project files from outside current working directory. e.g.

    $ tmuxp load /path/to/my/project/.tmuxp.yaml

    Will behave better with relative directories.


  • [config]: before_script now loads relative to project directory with ./.
  • [development]: Use bootstrap_env.py in tmuxp’s .tmuxp.yaml and .tmuxp.json project files.
  • [internal]: Improvements to util.run_before_script(), exc.BeforeLoadScriptFailed behavior to print stdout and return stderr is a non-zero exit is returned.
  • [internal]: run_script_before has moved to util.
  • [internal]: BeforeLoadScriptFailed and BeforeLoadScriptNotExists has moved to the exc module.
  • [internal]: Tests for run_script_before refactored.


2 bug fixes and allow panes with no shell commands to accept options, thanks for these 3 patches, @ThiefMaster:

  • [builder]: Issue #73: Fix an error caused by spaces in start_directory.
  • [builder]: Issue #77: Fix bug where having a - in a shell_command would cauesd a build error.
  • [config]: Issue #76: Don’t require shell_command to pass options to panes (like focus: true).


The --force was not with us.


  • [cli] [freezer]: Issue #72: Create destination directory if it doesn’t exist. Thanks @ThiefMaster.
  • [tests]: New context manager for tests, temp_session.
  • [tests]: New testsuite, testsuite.test_utils for testing testsuite tools.
  • [config] [builder]: New command, before_script, which is a file to be executed with a return code. It can be a bash, perl, python etc. script.
  • [docs]: Python API Quickstart per Issue #56.


  • [cli] [test]: Fix Issue #55 where tmuxp would crash with letter numbers in version. Write tests.


  • [internals] Window.split_window() now allows -c start_directory.

  • [builder] Issue #35 - Builder will now use -c start_directory to create new windows and panes.

    This removes a hack where default-path would be set for new pane and window creations. This would bleed into tmux user sessions after creations.

  • [packaging] fix Issue #49 bug where package_manifest.py missing from MANIFEST.in would cause error installing.


  • [docs] section heading normalization.
  • [docs] tao of tmux section now treated as a chatper. tao of tmux may be split off into its own project.
  • [internals] use conventions from tony/cookiecutter-pypackage.


  • [cli] Fix $ tmuxp freeze CLI output.
  • [internals] Update _compat support module.
  • [internals] Fix extra space in PEP 263.


  • [cli] Fix Python 3 CLI issue. Issue #48.
  • [cli] $ tmuxp without option raises an error. Issue #48.
  • [builder] - Add space before send-keys to not populate bash and zsh history.


  • [tests] now using werkzeug / flask style testsuites.
  • [cli] Merge Issue #43 - tmuxp -d for loading in detached mode. Thanks roxit.


  • [builder] [freezer] [bug] Fix Issue #32 where special characters caused unicode caused unexpected outcomes loading and freezing sessions.


  • [cli] fix duplicate print out of filename with using tmuxp load ..
  • version to 0.1. No --pre needed. Future versions will not use rc.


  • [internal] unicode_literals
  • [internal] Move py2/py3 compliancy code to _compat.



  • [config] [tests] [examples] Add Issue #31 from stratoukos - window_index option, and add example.


  • [tests] [config] [builder] Fix Issue #28 - shell_command_before in session scope of config causing duplication. New test.
  • [bug] Fix Issue #26 and Issue #29 for OS X tests. Thanks stratoukos.
  • [bug] Fix Issue #27 where $ tmuxp freeze raises unhelpful message if session doesn’t exist.


  • [bug] fix bug were focus: true would not launch sessions when using $ tmuxp load in a tmux session.


  • [bug] [tests] Issue #25 - focus: true not working in panes. Add tests for focusing panes in config.
  • [internal] Pane.select_pane().
  • [docs] add new example for focus: true.


  • [cli] [tests] - fix Issue #23 where workspace would not build with pane-base-index set to 1. Update tests to fix if pane-base-index is not 0.
  • [cli] - removed $ tmuxp load --list functionality. Update Quickstart accordingly.


  • [internal] pep8 and pep257 in unit tests.
  • Changelog will now be updated on a version basis, use pep440 versioning.





  • [cli] fix a bug where missing tmux didn’t show correct warning.


  • [tests] Travis now tests python 2.6 as requirement and not allowed to fail.


  • [cli] accept -y argument to answer yes to questions. #19
  • [cli] cli.SessionCompleter() no longer allows a duplicate session after one is added.
  • [docs] ongoing work on The Tao of tmux.



  • [cli] [freeze] - $ tmuxp freeze will now freeze a window with a start_directory when all panes in a window are inside the same directory.

  • [cli] [config] [tests] config.inline() will now turn panes with no other attributes and 1 command into a single item value.

    - panes:
      - shell_command: top
    # will now inline to:
    - panes
      - top
    This will improve ``$ tmuxp freeze``


  • [internal] Remove old logger (based on tornado’s log.py), replace with new, simpler one.
  • [cli] [import] fix teamocil import.
  • [import] [tests]: support import teamocil root to start_directory.


  • [cli] [tests] tagged v0.0.37. Many fixes. Python 2.6 support. Will switch to per-version changelog after 0.1 release..
  • [config] support for blank panes (null, pane, blank) and panes with empty strings.
  • [freeze] tmuxp freeze supports exporting to blank panes.
  • [freeze] tmuxp freeze will now return a blank pane for panes that would previously return a duplicate shell command, or generic python, node interpreter.


  • [cli] Support for [-L socket-name] and [-S socket-path] in autocompletion and when loading. Note, switching client into another socket may cause an error.
  • Documentation tweaking to API Reference, The Tao of tmux.
  • New Roadmap.
  • pep257, pep8.


  • [internal] [docs] - pep257, pep8.
  • tagged version v0.0.36.


  • [docs] Many documentation, pep257, pep8 fixes
  • [internal] move old Server methods __list_panes(), __list_windows and __list_sessions into the single underscore.
  • [cli] #12 bug fix for $ tmuxp freeze by @finder.
  • [cli] Support for spaces in $ tmuxp attach-session and $ tmuxp kill-session, and $ tmuxp freeze.
  • [config] [tests] support for relative paths of start_directory. Add an update config in Start Directory on Examples.


  • [internal] [tests] New servers for Server arguments socket_name, socket_path, config_file.
  • [internal] Server support for -2 with colors=256 and colors=8.
  • [cli] $ tmuxp -2 for forcing 256 colors and tmuxp -8 for forcing 88.
  • [config] [tests] Concatenation with start_directory via config.trickle() if window start_directory is alphanumeric / relative (doesn’t start with /). See Examples in start directory.
  • [import] Fix bug with import teamocil and tmuxinator
  • [import] Improve quality of tmuxinator imports. Especially session_name and start_directory.
  • [cli] Allow saving with ~ in file destination.


  • [internal] util.is_version()
  • [config] [tests]: correctly config.trickle() the start_directory.
  • [config] [tests]: get start_directory working for configs
  • [internal]: fix :meth:Window.kill_window() target to session_id:window_index for compatibility and pass tests.
  • [docs] [examples]: Example for start_directory.
  • [internal] fix bug where first and second window would load in mixed order
  • [internal] Window.move_window() for moving window.
  • [docs] major doc overhaul. front page, renamed orm_al.rst to internals.rst.


  • [cli] fix bug where if inside tmux, loading a workspace via switch_client wouldn’t work.
  • [cli] fix bug where tmuxp load . would return an error instead of a notice.
  • [cli] tmuxp freeze <filename> experimental
  • [freeze] [tests] tmuxp now has experimental support for freezing live sessions.
  • [internal] Window.kill_window()
  • [internal] support for start_directory (work in progress)


  • [internal] Window.select_pane() now accepts -l, -U, -D, -L, -R.
  • [internal] [tests] support for automatic-rename option.
  • [docs] 3 new Examples, ‘main-pane-height’, ‘automatic-rename’, and ‘shorthands’.
  • [cli] enhancements to prompts
  • [cli] tmuxp import for teamocil and tmuxinator now has a wizard and offers to save in JSON or YAML format.
  • [cli] [bug] [b6c2e84] Fix bug where tmuxp load w/ session already loaded would switch/attach even if no was entered
  • [cli] when workspace loader crashes, give option to kill session, attach it or detach it.
  • [cli] tmux 1.8 set-option / set-window-options command target-window fix.
  • [internal] WorkspaceBuilder now has .session attribute accessible publicly.
  • [cli] tmux will now use Session.switch_client() and Session.attach_session() to open new sessions instead of os.exec.
  • [config] tmuxp now allows a new shorter form for panes. Panes can just be a string. See the shorthand form in the Examples section.
  • [cli] [config] support loading .yml.


  • [cli] fix tmuxp load . fixed
  • [cli] fix tmuxp convert <file> fixed.
  • [internal] pep257 fixes.
  • [internal] [tests] - Pane now has Pane.set_width() and Pane.set_height().
  • [tests] ./run_tests.py --tests now automatically prepends tmuxp.testsuite to names.
  • [internal] Window.tmux() and Pane.tmux() will automatically add their {window/pane}_id if one isn’t specific.


  • [cli] argcomplete overhaul for CLI bash completion.
  • [cli] tmuxp load, tmuxp convert and tmuxp import now support relative and full filenames in addition to searching the config directory.


  • [import] [tests] initial version of tmuxinator and teamocil config importer. it does not support all options and it not guaranteed to fully convert window/pane size and state.
  • [internal] config.in_dir() supports a list of extensions for filetypes to search, i.e. ['.yaml', '.json'].
  • [internal] config.is_config_file() now supports extensions argument as a string also.
  • [cli] fix $ tmuxp load -l to work correctly alongside $ tmuxp load filename.


  • [cli] fix bug where -v and --version wouldn’t print version.
  • [cli] property handle case where no tmux server exists when attach-session or kill-session is used.
  • [import] [tests] test fixtures and inital work for importing tmuxinator and teamocil configs


  • [internal] clean out old code for automatic-rename option. it will be reimplemented fresh.
  • [cli] check for oh-my-zsh when using $SHELL zsh. Prompt if DISABLE_AUTO_TITLE is unset or set to true.
  • [cli] tmuxp can now $ tmuxp convert <file> from JSON <=> YAML, back and forth.
  • [docs] New examples in JSON. Update the Examples page in the docs.
  • [dev] .tmuxp.json now exists as a config for tmuxp development and as an example.
  • [cli] Fix bug where tmuxp kill-session would give bad output
  • [cli] Fix bug in tab completion for listing sessions with no tmux server is active.


  • [cli] zsh/bash/tcsh completion improvements for tab-completion options
  • [cli] tmuxp kill-session with tab-completion.
  • [cli] tmuxp attach-session with tab-completion. Attach session will switch-client for you if you are inside of of a tmux client.
  • [cli] tmuxp load for loading configs.
  • [tests] unit test fixes.


  • [cli] Make 1.8 the official minimym version, give warning notice to upgrade tmux if out of date
  • Fix regression causing unexpected build behavior due to unremoved code supporting old tmux versions.
  • [docs] Added 2 new examples to the Examples page.
  • [docs] Examples now have graphics
  • [cli] [internal] $ tmuxp -v will print the version info.



  • [internal] major internal overhaul of Server, Session, Window, and Pane.
    • Session, Window and Pane now refer to a data object in Server internally and always pull the freshest data.
    • A lot of code and complexity regarding setting new data for objects has been reduced since objects use their unique key identifier to filter their objects through the windows and panes in Server object.
    • Server object is what does the updating now.
  • [project] some research into supporting legacy tmux versions. tmux 1.6 and 1.7 support seem likely eventually if there is enough demand.
  • [internal] python 3 support


  • [docs] updated README docs with new project details, screenshots
  • [dev] [docs] - new example .tmuxp.yaml file updated to include development workflow. Removed nodemon as the tool for checking files for now.
  • [cli] Support for switching sessions from within tmux. In both cases after the the session is built and if session already exists.



  • [docs] new theme

  • [docs] initial examples, misc. updates, front page update.

  • [cli] support for $ tmux . to load .tmuxp.{yaml/json/py} in current working directory.

  • [cli] support for socket-name (-L) and socket-path (socket-path)

  • [config] [builder] Support for 1-command pane items.

    session_name: my session
      - window_name: hi
        - bash
        - htop
  • [cli] If session name is already exists, prompt to attach.


  • [cli] can now -l to list configs in current directory and $HOME/.tmuxp
  • [cli] tmuxp can now launch configs and build sessions
  • [internal] new exceptions
  • [config] [tests] config.check_consistency() to verify and diagnose issues with config files.
  • [cli] [tests] cli.startup()
  • [config] [tests] config.is_config_file()
  • [config] [tests] config.in_dir()
  • [config] [tests] config.in_cwd()


  • [cli] [tests] config.inline() to produce far far better looking config exports and tests.
  • Pane.resize_pane() and tests
  • documentation fixes and updates
  • [internal] Session.refresh(), Window.refresh(), Pane.refresh().
  • [internal] Server.find(), Session.find(), Window.find().



  • [builder] More preparation for builder / session maker utility.
  • [tests] Major test runner and test suite overhaul.
  • [docs] Documentation for development environment and test runner updated.
  • [tests] Travis now tests against tmux 1.8 and latest source. Door open for future testing against python 3 and earlier tmux versions in the future.
  • [internal] Quiet logger down in some areas
  • [internal] __future__ imports for future python 3 compatibility
  • [internal] setup.py import __version__ via regex from tmuxp package
  • [cli] move beginnings of cli to tmuxp.cli


  • New logging module
  • Removed dependency logutils
  • Removed dependency sh


  • switch to semver