class libtmux.Session(server=None, **kwargs)

Bases: libtmux.common.TmuxMappingObject, libtmux.common.TmuxRelationalObject, libtmux.common.EnvironmentMixin

tmux(1) session.

Holds Window objects.

child_id_attribute = u'window_id'

unique child ID key for TmuxRelationalObject

formatter_prefix = u'session_'

namespace used TmuxMappingObject

cmd(*args, **kwargs)

Return server.cmd().

Return type:server.cmd

Changed in version 0.8: Renamed from .tmux to .cmd.


Return $ tmux attach-session aka alias: $ tmux attach.


$ tmux kill-session.


$ tmux switch-client.

Param:target_session: str. note this accepts fnmatch(3).

Rename session and return new Session object.

Parameters:new_name (str) – new session name
Return type:Session
new_window(window_name=None, start_directory=None, attach=True, window_index=u'', window_shell=None)

Return Window from $ tmux new-window.

By default, this will make the window active. For the new window to be created and not set to current, pass in attach=False.

  • window_name (str) – window name.
  • start_directory (str) – specifies the working directory in which the new window is created.
  • attach – make new window the current window after creating it, default True.
  • window_index (str) – create the new window at the given index position. Default is empty string which will create the window in the next available position.
  • window_shell – execute a command on starting the window. The window will close when the command exits. NOTE: When this command exits the window will close. This feature is useful for long-running processes where the closing of the window upon completion is desired.
  • type – bool
Return type:



$ tmux kill-window.

Kill the current window or the window at target-window. removing it from any sessions to which it is linked.

Parameters:target_window (str) – the target window.

Property / alias to return Session._list_windows().


Return a list of Window from the tmux(1) session.

Return type:Window

Property / alias to return Session.list_windows().


Alias windows for TmuxRelationalObject


Return active Window object.

Return type:Window

Return Window selected via $ tmux select-window.

Param:window: target_window also ‘last-window’ (-l), ‘next-window’ (-n), or ‘previous-window’ (-p)
Return type:Window
Todo:assure -l, -n, -p work.

Return active Pane object.

set_option(option, value, g=False)

Set option $ tmux set-option <option> <value>.

todo: needs tests

  • option (str) – the window option. such as ‘default-shell’.
  • value (bool) – window value. True/False will turn in ‘on’ and ‘off’. You can also enter ‘on’ or ‘off’ directly.
  • global (bool) – check for option globally across all servers (-g)

exc.OptionError, exc.UnknownOption, exc.InvalidOption, exc.AmbiguousOption

show_options(option=None, g=False)

Return a dict of options for the window.

For familiarity with tmux, the option option param forwards to pick a single option, forwarding to Session.show_option().

  • option (str) – optional. show a single option.
  • g (bool) – Pass -g flag for global variable (server-wide)
Return type:


show_option(option, g=False)

Return a list of options for the window.


test and return True/False for on/off string

  • option (str) – option to return.
  • global (bool) – check for option globally across all servers (-g)
Return type:

str, int or bool


exc.OptionError, exc.UnknownOption, exc.InvalidOption, exc.AmbiguousOption

clear() → None. Remove all items from D.

Return object on first match.

Changed in version 0.4: Renamed from .findWhere to .find_where.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

Return object based on child_id_attribute.

Based on .get() from backbone.js.

Parameters:id (str) –
Return type:object
items() → list of D's (key, value) pairs, as 2-tuples
iteritems() → an iterator over the (key, value) items of D
iterkeys() → an iterator over the keys of D
itervalues() → an iterator over the values of D

Return list of keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.


Remove environment variable $ tmux set-environment -r <name>.

Parameters:name – the environment variable name. such as ‘PATH’.
set_environment(name, value)

Set environment $ tmux set-environment <name> <value>.

  • name – the environment variable name. such as ‘PATH’.
  • value (str) – environment value.
setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

Show environment $tmux show-environment -t [session] <name>.

Return dict of environment variables for the session or the value of a specific variable if the name is specified.

Parameters:name – the environment variable name. such as ‘PATH’.

Unset environment variable $ tmux set-environment -u <name>.

Parameters:name – the environment variable name. such as ‘PATH’.
update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → list of D's values
where(attrs, first=False)

Return objects matching child objects properties.

Parameters:attrs (dict) – tmux properties to match
Return type:list