README.md
1libtmux - scripting library for tmux
2
3[](http://badge.fury.io/py/libtmux)
4[](https://github.com/tmux-python/libtmux/actions?query=workflow%3A%22Publish+Docs%22)
5[](https://github.com/tmux-python/tmux-python/actions?query=workflow%3A%22tests%22)
6[](https://codecov.io/gh/tmux-python/libtmux)
7
8
9libtmux is the tool behind [tmuxp](https://tmuxp.git-pull.com/), a tmux
10workspace manager in python.
11
12it builds upon tmux's
13[target](http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#COMMANDS) and
14[formats](http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#FORMATS) to
15create an object mapping to traverse, inspect and interact with live
16tmux sessions.
17
18view the [documentation](https://libtmux.git-pull.com/) homepage,
19[API](https://libtmux.git-pull.com/api.html) information and
20[architectural details](https://libtmux.git-pull.com/about.html).
21
22Python 2.x will be deprecated in libtmux 0.9. The backports branch is
23[v0.8.x](https://github.com/tmux-python/libtmux/tree/v0.8.x).
24
25# install
26
27```sh
28$ [sudo] pip install libtmux
29```
30
31# open a tmux session
32
33session name `foo`, window name `bar`
34
35```sh
36$ tmux new-session -s foo -n bar
37```
38
39# pilot your tmux session via python
40
41```sh
42$ python
43
44# or for nice autocomplete and syntax highlighting
45$ pip install ptpython
46$ ptpython
47```
48
49connect to a live tmux session:
50
51```python
52>>> import libtmux
53>>> server = libtmux.Server()
54>>> server
55<libtmux.server.Server object at 0x7fbd622c1dd0>
56```
57
58list sessions:
59
60```python
61>>> server.list_sessions()
62[Session($3 foo), Session($1 libtmux)]
63```
64
65find session:
66
67```python
68>>> server.get_by_id('$3')
69Session($3 foo)
70```
71
72find session by dict lookup:
73
74```python
75>>> server.find_where({ "session_name": "foo" })
76Session($3 foo)
77```
78
79assign session to `session`:
80
81```python
82>>> session = server.find_where({ "session_name": "foo" })
83```
84
85play with session:
86
87```python
88>>> session.new_window(attach=False, window_name="ha in the bg")
89Window(@8 2:ha in the bg, Session($3 foo))
90>>> session.kill_window("ha in")
91```
92
93create new window in the background (don't switch to it):
94
95```python
96>>> w = session.new_window(attach=False, window_name="ha in the bg")
97Window(@11 3:ha in the bg, Session($3 foo))
98```
99
100kill window object directly:
101
102```python
103>>> w.kill_window()
104```
105
106grab remaining tmux window:
107
108```python
109>>> window = session.attached_window
110>>> window.split_window(attach=False)
111Pane(%23 Window(@10 1:bar, Session($3 foo)))
112```
113
114rename window:
115
116```python
117>>> window.rename_window('libtmuxower')
118Window(@10 1:libtmuxower, Session($3 foo))
119```
120
121create panes by splitting window:
122
123```python
124>>> pane = window.split_window()
125>>> pane = window.split_window(attach=False)
126>>> pane.select_pane()
127>>> window = session.new_window(attach=False, window_name="test")
128>>> pane = window.split_window(attach=False)
129```
130
131send key strokes to panes:
132
133```python
134>>> pane.send_keys('echo hey send now')
135
136>>> pane.send_keys('echo hey', enter=False)
137>>> pane.enter()
138```
139
140grab the output of pane:
141
142```python
143>>> pane.clear() # clear the pane
144>>> pane.send_keys('cowsay hello')
145>>> print('\n'.join(pane.cmd('capture-pane', '-p').stdout))
146```
147
148 sh-3.2$ cowsay 'hello'
149 _______
150 < hello >
151 -------
152 \ ^__^
153 \ (oo)\_______
154 (__)\ )\/\
155 ||----w |
156 || ||
157
158powerful traversal features:
159
160 >>> pane.window
161 Window(@10 1:libtmuxower, Session($3 foo))
162 >>> pane.window.session
163 Session($3 foo)
164
165# Donations
166
167Your donations fund development of new features, testing and support.
168Your money will go directly to maintenance and development of the
169project. If you are an individual, feel free to give whatever feels
170right for the value you get out of the project.
171
172See donation options at <https://git-pull.com/support.html>.
173
174# Project details
175
176- tmux support: 1.8, 1.9a, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
177- python support: >= 3.6, pypy, pypy3
178- Source: <https://github.com/tmux-python/libtmux>
179- Docs: <https://libtmux.git-pull.com>
180- API: <https://libtmux.git-pull.com/api.html>
181- Changelog: <https://libtmux.git-pull.com/history.html>
182- Issues: <https://github.com/tmux-python/libtmux/issues>
183- Test Coverage: <https://codecov.io/gh/tmux-python/libtmux>
184- pypi: <https://pypi.python.org/pypi/libtmux>
185- Open Hub: <https://www.openhub.net/p/libtmux-python>
186- License: [MIT](http://opensource.org/licenses/MIT).
187
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}