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.

TMUXP_CONFIGDIR environmental variable has precedence if set. We also evaluate XDG default directory from XDG_CONFIG_HOME environmental variable if set or its default. Then the old default ~/.tmuxp is returned for compatibility.

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)[source]

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 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!).

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=['.yml', '.yaml', '.json'])[source]

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=['.yml', '.yaml', '.json'])[source]

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)[source]

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

class tmuxp.workspacebuilder.WorkspaceBuilder(sconf, server=None)[source]

Load workspace from session dict.

Build tmux workspace from a configuration. Creates and names windows, sets options, splits windows into panes.

The normal phase of loading is:

  1. kaptan imports json/yaml/ini. .get() returns python dict:

    import kaptan
    sconf = kaptan.Kaptan(handler='yaml')
    sconf = sconfig.import_config(self.yaml_config).get()

    or from config file with extension:

    import kaptan
    sconf = kaptan.Kaptan()
    sconf = sconfig.import_config('path/to/config.yaml').get()

    kaptan automatically detects the handler from filenames.

  2. config.expand() sconf inline shorthand:

    from tmuxp import config
    sconf = config.expand(sconf)
  3. config.trickle() passes down default values from session -> window -> pane if applicable:

    sconf = config.trickle(sconf)
  4. (You are here) We will create a libtmux.Session (a real tmux(1) session) and iterate through the list of windows, and their panes, returning full libtmux.Window and libtmux.Pane objects each step of the way:

    workspace = WorkspaceBuilder(sconf=sconf)

It handles the magic of cases where the user may want to start a session inside tmux (when $TMUX is in the env variables).


Build tmux workspace in session.

Optionally accepts session to build with only session object.

Without session, it will use libmtux.Server at self.server passed in on initialization to create a new Session object.

Parameters:session (libtmux.Session) – session to build workspace in
config_after_window(w, wconf)[source]

Actions to apply to window after window and pane finished.

When building a tmux session, sometimes its easier to postpone things like setting options until after things are already structurally prepared.

  • w (libtmux.Window) – window to create panes for
  • wconf (dict) – config section for window
iter_create_panes(w, wconf)[source]

Return libtmux.Pane iterating through window config dict.

Run shell_command with $ tmux send-keys.

  • w (libtmux.Window) – window to create panes for
  • wconf (dict) – config section for window

Newly created pane, and the section from the tmuxp configuration that was used to create the pane.

Return type:

tuple of (libtmux.Pane, pconf)


Return libtmux.Window iterating through session config dict.

Generator yielding libtmux.Window by iterating through sconf['windows'].

Applies window_options to window.

Parameters:session (libtmux.Session) – session to create windows in
Returns:Newly created window, and the section from the tmuxp configuration that was used to create the window.
Return type:tuple of (libtmux.Window, wconf)

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[source]

Configuration is empty.

exception tmuxp.exc.ConfigError[source]

Error parsing tmuxp configuration dict.

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

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

exception tmuxp.exc.BeforeLoadScriptNotExists(*args, **kwargs)[source]