tmux-python/libtmuxPublic

NotificationsYou must be signed in to change notification settings
Fork112
Star1.1k

⚙️ Python API / wrapper for tmux

License

MIT license

1.1k stars 112 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 2,135 Commits
.cursor/rules		.cursor/rules
.github		.github
.vim		.vim
docs		docs
src/libtmux		src/libtmux
tests		tests
.codecov.yml		.codecov.yml
.gitignore		.gitignore
.prettierrc		.prettierrc
.python-version		.python-version
.tmuxp.yaml		.tmuxp.yaml
.tool-versions		.tool-versions
CHANGES		CHANGES
CITATION.cff		CITATION.cff
LICENSE		LICENSE
MIGRATION		MIGRATION
Makefile		Makefile
README.md		README.md
TODO		TODO
conftest.py		conftest.py
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Repository files navigation

libtmux

libtmux is atyped Python library that provides a wrapper for interacting programmatically with tmux, a terminal multiplexer. You can use it to manage tmux servers,sessions, windows, and panes. Additionally,libtmux powerstmuxp, a tmux workspace manager.

Key Features

Intuitive API: Control tmux servers, sessions, windows, and panes with a clean, object-oriented interface
Complete Automation: Create and manage complex tmux environments programmatically
Type Annotations: Full typing support for modern Python development
Pytest Plugin: Built-in testing tools for tmux automation
Context Managers: Safe session and window management with Python's context protocol
Robust Architecture: Built on tmux's native concepts of targets and formats

libtmux builds upon tmux'starget andformats tocreate an object mapping to traverse, inspect and interact with livetmux sessions.

View thedocumentation,API information andarchitectural details.

Use Cases

Development Environment Automation: Set up consistent workspaces across projects
CI/CD Systems: Create isolated environments for testing and deployment
System Monitoring: Build interactive dashboards for server administration
Remote Pair Programming: Facilitate collaborative development sessions
Data Science Workflows: Manage complex data processing pipelines
Education and Demonstrations: Create multi-window learning environments

For more detailed examples, see ouruse cases documentation.

Install

$pip install --user libtmux

Open a tmux session

Session namefoo, window namebar

$tmux new-session -s foo -n bar

Pilot your tmux session via python

$python

Useptpython,ipython, etc. for a nice shell with autocompletions:

$pip install --user ptpython

$ptpython

Connect to a live tmux session:

>>>importlibtmux>>>svr=libtmux.Server()>>>svrServer(socket_path=/tmp/tmux-.../default)

Tip: You can also usetmuxp'stmuxp shell to drop straight into yourcurrent tmux server / session / window pane.

Run any tmux command, respective of context:

Honors tmux socket name and path:

>>>server=Server(socket_name='libtmux_doctest')>>>server.cmd('display-message','hello world')<libtmux...>

New session:

>>>server.cmd('new-session','-d','-P','-F#{session_id}').stdout[0]'$2'

>>>session.cmd('new-window','-P').stdout[0]'libtmux...:2.0'

From raw command output, to a richWindow object (in practice and as shownlater, you'd useSession.new_window()):

>>>Window.from_window_id(window_id=session.cmd('new-window','-P','-F#{window_id}').stdout[0],server=session.server)Window(@22:...,Session($1libtmux_...))

Create a pane from a window:

>>>window.cmd('split-window','-P','-F#{pane_id}').stdout[0]'%2'

Raw output directly to aPane:

>>>Pane.from_pane_id(pane_id=window.cmd('split-window','-P','-F#{pane_id}').stdout[0],server=window.server)Pane(%...Window(@11:...,Session($1libtmux_...)))

List sessions:

>>>server.sessions[Session($1 ...),Session($0 ...)]

Filter sessions by attribute:

>>>server.sessions.filter(history_limit='2000')[Session($1 ...),Session($0 ...)]

Direct lookup:

>>>server.sessions.get(session_id="$1")Session($1 ...)

Filter sessions:

>>>server.sessions[0].rename_session('foo')Session($1foo)>>>server.sessions.filter(session_name="foo")[Session($1foo)]>>>server.sessions.get(session_name="foo")Session($1foo)

Control your session:

>>>sessionSession($1 ...)>>>session.rename_session('my-session')Session($1my-session)

Create new window in the background (don't switch to it):

>>>bg_window=session.new_window(attach=False,window_name="ha in the bg")>>>bg_windowWindow(@...2:hainthebg,Session($1 ...))# Session can search the window>>>session.windows.filter(window_name__startswith="ha")[Window(@...2:hainthebg,Session($1 ...))]# Directly>>>session.windows.get(window_name__startswith="ha")Window(@...2:hainthebg,Session($1 ...))# Clean up>>>bg_window.kill()

Close window:

>>>w=session.active_window>>>w.kill()

Grab remaining tmux window:

>>>window=session.active_window>>>window.split(attach=False)Pane(%2Window(@11:...Session($1 ...)))

Rename window:

>>>window.rename_window('libtmuxower')Window(@11:libtmuxower,Session($1 ...))

Split window (create a new pane):

>>>pane=window.split()>>>pane=window.split(attach=False)>>>pane.select()Pane(%3Window(@11:...,Session($1 ...)))>>>window=session.new_window(attach=False,window_name="test")>>>windowWindow(@22:test,Session($1 ...))>>>pane=window.split(attach=False)>>>panePane(%5Window(@22:test,Session($1 ...)))

Type inside the pane (send key strokes):

>>>pane.send_keys('echo hey send now')>>>pane.send_keys('echo hey',enter=False)>>>pane.enter()Pane(%1 ...)

Grab the output of pane:

>>>pane.clear()# clear the panePane(%1 ...)>>>pane.send_keys("cowsay 'hello'",enter=True)>>>print('\n'.join(pane.cmd('capture-pane','-p').stdout))# doctest: +SKIP$cowsay'hello'_______<hello>-------        \^__^         \  (oo)\_______            (__)\       )\/\||----w|||||...

Traverse and navigate:

>>>pane.windowWindow(@11:...,Session($1 ...))>>>pane.window.sessionSession($1 ...)

Testing with pytest

libtmux includes a pytest plugin that provides fixtures for testing tmux operations:

deftest_session_creation(session):"""Test creating a new window in the session."""window=session.new_window(window_name="test_window")assertwindow.window_name=="test_window"# Create a new panepane=window.split_window()assertlen(window.panes)==2# Send keys to the panepane.send_keys("echo 'Hello from test'")

Seepytest plugin documentation for more details.

Advanced Usage

libtmux supports a wide range of advanced use cases:

Context Managers

Safely manage sessions and windows with Python's context protocol:

withServer().new_session(session_name="my_session")assession:window=session.new_window(window_name="my_window")# Work with the window...# Session is properly cleaned up when context exits

Advanced Scripting

Create complex window layouts and integrate with external systems:

session=server.new_session(session_name="dashboard")main=session.new_window(window_name="main")# Create a grid layout with 4 panestop_left=main.attached_panetop_right=top_left.split_window(vertical=True)bottom_left=top_left.split_window(vertical=False)bottom_right=top_right.split_window(vertical=False)# Configure each panetop_left.send_keys("htop",enter=True)top_right.send_keys("watch -n 1 df -h",enter=True)bottom_left.send_keys("tail -f /var/log/syslog",enter=True)bottom_right.send_keys("netstat -tunapl",enter=True)

Seeadvanced scripting documentation for more examples.

Python support

Unsupported / no security releases or bug fixes:

Python 2.x: The backports branch isv0.8.x.

Donations

Your donations fund development of new features, testing and support.Your money will go directly to maintenance and development of theproject. If you are an individual, feel free to give whatever feelsright for the value you get out of the project.

See donation options athttps://git-pull.com/support.html.