API Reference

See also

See libtmux’s API and Quickstart to see how you can control tmux via python API calls.



Function to wrap try/except for subprocess.check_call().



Reattach session (depending on env being inside tmux already or not)

Parameters:session (libtmux.Session) –


If TMUX environmental variable exists in the environment this script is running, that means we’re in a tmux client. So tmux switch-client will load the session.

If not, tmux attach-session loads the client to the target session.


Return tmuxp configuration directory.

Checks for TMUXP_CONFIGDIR environmental variable.

Returns:absolute path to tmuxp config directory
Return type:str

Return teamocil configuration directory.

Returns:absolute path to teamocil config directory
Return type:str

Return tmuxinator configuration directory.

Checks for TMUXINATOR_CONFIG environmental variable.

Returns:absolute path to tmuxinator config directory
Return type:str
cli.load_workspace(socket_name=None, socket_path=None, colors=None, detached=False, answer_yes=False)

Load a tmux “workspace” session via tmuxp file.

  • config_file (str) – absolute path to config file
  • socket_name (str, optional) – tmux -L <socket-name>
  • socket_path (str, optional) – tmux -S <socket-path>
  • colors (str, optional) –
    Force tmux to support 256 colors
  • detached (bool) – Force detached state. default False.
  • answer_yes (bool) – Assume yes when given prompt. default False.


tmuxp will check and load a configuration file. The file will use kaptan to load a JSON/YAML into a dict. Then config.expand() and config.trickle() will be used to expand any shorthands, template variables, or file paths relative to where the config/script is executed from.

config.expand() accepts the directory of the config file, so the user’s configuration can resolve absolute paths relative to where the config file is. In otherwords, if a config file at /var/moo/hi.yaml has ./ in its configs, we want to be sure any file path with ./ is relative to /var/moo, not the user’s PWD.

A libtmux.Server object is created. No tmux server is started yet, just the object.

The prepared configuration and the server object is passed into an instance of tmuxp.WorkspaceBuilder.

A sanity check against libtmux.common.which() is ran. It will raise an exception if tmux isn’t found.

If a tmux session under the same name as session_name in the tmuxp configuration exists, tmuxp offers to attach the session. Currently, tmuxp does not allow appending a workspace / incremental building on top of a current session (pull requests are welcome!).

tmuxp.WorkspaceBuilder.build() will build the session in the background via using tmux’s detached state (-d).

After the session (workspace) is built, unless the user decided to load the session in the background via tmuxp -d (which is in the spirit of tmux’s -d), we need to prompt the user to attach the session.

If the user is already inside a tmux client, which we detect via the TMUX environment variable bring present, we will prompt the user to switch their current client to it.

If they’re outside of tmux client - in a plain-old PTY - we will automatically attach.

If an exception is raised during the building of the workspace, tmuxp will prompt to cleanup ($ tmux kill-session) the session on the user’s behalf. An exception raised during this process means it’s not easy to predict how broken the session is.

Changed in version tmux: 2.6+

In tmux 2.6, the way layout and proportion’s work when interfacing with tmux in a detached state (outside of a client) changed. Since tmuxp builds workspaces in a detached state, the WorkspaceBuilder isn’t able to rely on functionality requiring awarness of session geometry, e.g. set-layout.

Thankfully, tmux is able to defer commands to run after the user performs certain actions, such as loading a client via attach-session or switch-client.

Upon client switch, client-session-changed is triggered [1].


[1]cmd-switch-client.c hook. GitHub repo for tmux. https://github.com/tmux/tmux/blob/2.6/cmd-switch-client.c#L132. Accessed April 8th, 2018.

Callback wrapper for validating click.prompt input.

Parameters:options (list) – List of allowed choices
Returns:callback function for value_proc in click.prompt().
Return type:callable()



config.is_config_file(extensions=[u'.yml', u'.yaml', u'.json'])

Return True if file has a valid config file type.

  • filename (str) – filename to check (e.g. mysession.json).
  • extensions (str or list) – filetypes to check (e.g. ['.yaml', '.json']).

Return type:


config.in_dir(extensions=[u'.yml', u'.yaml', u'.json'])

Return a list of configs in config_dir.

  • config_dir (str) – directory to search
  • extensions (list) – filetypes to check (e.g. ['.yaml', '.json']).

Return type:



Return list of configs in current working directory.

If filename is .tmuxp.py, .tmuxp.json, .tmuxp.yaml.

Returns:configs in current working directory
Return type:list

Import and export


Return True if config schema is correct.

Parameters:sconf (dict) – session configuration
Return type:bool

Return expanded path based on user’s $HOME and env.

os.path.expanduser() and os.path.expandvars()

Parameters:path (str) – path to expand
Returns:path with shell variables expanded
Return type:str
config.expand(cwd=None, parent=None)

Return config with shorthand and inline properties expanded.

This is necessary to keep the code in the WorkspaceBuilder clean and also allow for neat, short-hand configurations.

As a simple example, internally, tmuxp expects that config options like shell_command are a list (array):

'shell_command': ['htop']

tmuxp configs allow for it to be simply a string:

'shell_command': 'htop'

Kaptan will load JSON/YAML files into python dicts for you.

  • sconf (dict) – the configuration for the session
  • cwd (str) – directory to expand relative paths against. should be the dir of the config directory.
  • parent (str) – (used on recursive entries) start_directory of parent window or session object.

Return type:



Return config in inline form, opposite of config.expand().

Parameters:sconf (dict) –
Returns:configuration with optional inlined configs.
Return type:dict

Return a dict with “trickled down” / inherited config values.

This will only work if config has been expanded to full form with config.expand().

tmuxp allows certain commands to be default at the session, window level. shell_command_before trickles down and prepends the shell_command for the pane.

Parameters:sconf (dict) – the session configuration.
Return type:dict

Return tmuxp config from a teamocil yaml config.

Parameters:sconf (dict) – python dict for session configuration



  • change ‘root’ to a cd or start_directory
  • width in pane -> main-pain-width
  • with_env_var
  • clear
  • cmd_separator

Return tmuxp config from a tmuxinator yaml config.

Parameters:sconf (dict) – python dict for session configuration.
Return type:dict

Workspace Builder


Freeze live tmux session and Return session config dict.

Parameters:session (libtmux.Session) – session object
Returns:tmuxp compatible workspace config
Return type:dict


exception tmuxp.exc.EmptyConfigException

Configuration is empty.

exception tmuxp.exc.ConfigError

Error parsing tmuxp configuration dict.

exception tmuxp.exc.BeforeLoadScriptError(returncode, cmd, output=None)

Exception replacing subprocess.CalledProcessError for util.run_before_script().

exception tmuxp.exc.BeforeLoadScriptNotExists(*args, **kwargs)