Quickstart

libtmux allows for developers and system administrators to control live tmux sessions using python code.

In this example, we will launch a tmux session and control the windows from inside a live tmux session.

Requirements

  • tmux
  • pip - for this handbook’s examples

Installation

Next, ensure libtmux is installed:

$ [sudo] pip install libtmux

Start a tmux session

Now, let’s open a tmux session.

$ tmux new-session -n bar -s foo

This tutorial will be using the session and window name in the example.

Window name -n: bar Session name -s: foo

Control tmux via python

See also

API Reference

$ python

For commandline completion, you can also use ptpython.

$ [sudo] pip install ptpython
$ ptpython

First, we can grab a Server.

>>> import libtmux
>>> server = libtmux.Server()
>>> server
<libtmux.server.Server object at 0x7fbd622c1dd0>

Note

You can specify a socket_name, socket_path and config_file in your server object. libtmux.Server(socket_name='mysocket') is equivalent to $ tmux -L mysocket.

server is now a living object bound to the tmux server’s Sessions, Windows and Panes.

Find your Session

If you have multiple tmux sessions open, you can see that all of the methods in Server are available.

We can list sessions with Server.list_sessions():

>>> server.list_sessions()
[Session($3 foo), Session($1 libtmux)]

This returns a list of Session objects you can grab. We can find our current session with:

>>> server.list_sessions()[0]

However, this isn’t guaranteed, libtmux works against current tmux information, the session’s name could be changed, or another tmux session may be created, so Server.get_by_id() and Server.find_where() exists as a lookup.

Get session by ID

tmux sessions use the $[0-9] convention as a way to identify sessions.

$3 is whatever the ID list_sessions() returned above.

>>> server.get_by_id('$3')
Session($3 foo)

You may session = server.get_by_id('$<yourId>') to use the session object.

Get session by name / other properties

>>> server.find_where({ "session_name": "foo" })
Session($3 foo)

With find_where, pass in a dict and return the first object found. In this case, a Server holds a collection of child Session. Session and Window both utilize find_where to sift through Windows and Panes, respectively.

So you may now use:

>>> session = server.find_where({ "session_name": "foo" })

to give us a session object to play with.

Playing with our tmux session

We now have access to session from above with all of the methods available in Session.

Let’s make a Session.new_window(), in the background:

>>> session.new_window(attach=False, window_name="ha in the bg")
Window(@8 2:ha in the bg, Session($3 foo))

So a few things:

  1. attach=False meant to create a new window, but not to switch to it. It is the same as $ tmux new-window -d.
  2. window_name may be specified.
  3. Returns the Window object created.

Note

Use the API reference API Reference for more commands.

Let’s delete that window (Session.kill_window()).

Method 1: Use passthrough to tmux’s target system.

>>> session.kill_window("ha in")

The window in the bg dissappeared. This was the equivalent of $ tmux kill-window -t'ha in'

Internally, tmux uses target. Its specific behavior depends on what the target is, view the tmux manpage for more information:

This section contains a list of the commands supported by tmux.  Most commands
accept the optional -t argument with one of target-client, target-session,
target-window, or target-pane.

In this case, you can also go back in time and recreate the window again. The CLI should have history, so navigate up with the arrow key.

>>> session.new_window(attach=False, window_name="ha in the bg")
Window(@11 3:ha in the bg, Session($3 foo))

Try to kill the window by the matching id @[0-9999].

>>> session.new_window(attach=False, window_name="ha in the bg")
Window(@12 3:ha in the bg, Session($3 foo))

In addition, you could also .kill_window direction from the Window object:

>>> window = session.new_window(attach=False, window_name="check this out")

And kill:

>>> window.kill_window()

Use Session.list_windows() and Session.find_where() to list and sort through active Window’s.

Manipulating windows

Now that we know how to create windows, let’s use one. Let’s use Session.attached_window() to grab our current window.

>>> window = session.attached_window()

window now has access to all of the objects inside of Window.

Let’s create a pane, Window.split_window():

>>> window.split_window(attach=False)
Pane(%23 Window(@10 1:bar, Session($3 foo)))

Powered up. Let’s have a break down:

  1. window = session.attached_window() gave us the Window of the current attached to window.
  2. attach=False assures the cursor didn’t switch to the newly created pane.
  3. Returned the created Pane.

Also, since you are aware of this power, let’s commemorate the experience:

>>> window.rename_window('libtmuxower')
Window(@10 1:libtmuxower, Session($3 foo))

You should have noticed Window.rename_window() renamed the window.

Moving cursor across windows and panes

You have two ways you can move your cursor to new sessions, windows and panes.

For one, arguments such as attach=False can be omittted.

>>> pane = window.split_window()

This gives you the Pane along with moving the cursor to a new window. You can also use the .select_* available on the object, in this case the pane has Pane.select_pane().

>>> pane = window.split_window(attach=False)
>>> pane.select_pane()

Sending commands to tmux panes remotely

You may send commands to panes, windows and sessions without them being visible. As long as you have the object, or are iterating through a list of them, you can use .send_keys.

>>> window = session.new_window(attach=False, window_name="test")
>>> pane = window.split_window(attach=False)
>>> pane.send_keys('echo hey', enter=False)

See the other window, notice that Pane.send_keys() has ” echo hey” written, still in the prompt. Note the leading space character so the command won’t be added to the user’s history. Use pane.cmd(‘send-keys’, text) to send keys without this leading space.

enter=False can be used to send keys without pressing return. In this case, you may leave it to the user to press return himself, or complete a command using Pane.enter():

>>> pane.enter()

Final notes

These objects created use tmux’s internal usage of ID’s to make servers, sessions, windows and panes accessible at the object level.

You don’t have to see the tmux session to be able to orchestrate it. After all, WorkspaceBuilder uses these same internals to build your sessions in the background. :)

See also

If you want to dig deeper, check out API Reference, the code for and our test suite (see Developing and Testing.)