API Reference

See also

python_api_quickstart to see how you can control tmux via python API calls.



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



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

Return True if file has a valid config file type.

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


config.in_dir(config_dir=u'/home/docs/.tmuxp', extensions=[u'.yml', u'.yaml', u'.json'])

Return a list of configs in config_dir.

  • config_dir (string) – 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.

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 (string) – path to expand
Returns:expanded path
Return type:string
config.expand(sconf, 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 (string) – 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) – unexpanded config file
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.

Todo:change ‘root’ to a cd or start_directory
Todo:width in pane -> main-pain-width
Parameters:sconf (dict) – python dict for session configuration

Return tmuxp config from a tmuxinator yaml config.

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

Workspace Builder

class tmuxp.WorkspaceBuilder(sconf, server=None)

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 Session (a real tmux(1) session) and iterate through the list of windows, and their panes, returning full Window and 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 Server at self.server passed in on initialization to create a new Session object.

Parameters:session (Session) –
  • session to build workspace in
iter_create_panes(w, wconf)

Return Pane iterating through window config dict.

Run shell_command with $ tmux send-keys.

  • w (Window) – window to create panes for
  • wconf (dict) – config section for window
Return type:

tuple(Pane, pconf)


Return Window iterating through session config dict.

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

Applies window_options to window.

Parameters:sessionSession from the config
Return type:tuple(Window, wconf)


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)