tmuxp shell

Launch an interactive Python shell with libtmux objects pre-loaded. Like Django’s shell command, it hands you the current tmux server, sessions, windows, and panes already wired up, so you can poke at a live session or prototype a script without writing boilerplate.

Command

Launch interactive Python shell with tmux server, session, window and pane.

Usage

usage: tmuxp shell [-h] [-S socket-path] [-L socket-name] [-c COMMAND]
                   [--best | --pdb | --code | --ptipython | --ptpython |
                   --ipython | --bpython] [--use-pythonrc] [--no-startup]
                   [--use-vi-mode] [--no-vi-mode]
                   [session-name] [window-name]

Examples

$ tmuxp shell

$ tmuxp shell -L mysocket

$ tmuxp shell -c 'print(server.sessions)'

$ tmuxp shell --best

Positional Arguments

session_name session-name
Default
None
window_name window-name
Default
None

Options

-S socket-path

pass-through for tmux -S

Default
None
-L socket-name

pass-through for tmux -L

Default
None
-c

instead of opening shell, execute python code in libtmux and exit

Default
None
--use-pythonrc

load PYTHONSTARTUP env var and ~/.pythonrc.py script in --code

Default
False
--no-startup

load PYTHONSTARTUP env var and ~/.pythonrc.py script in --code

Default
False
--use-vi-mode

use vi-mode in ptpython/ptipython

Default
False
--no-vi-mode

use vi-mode in ptpython/ptipython

Default
False
--best

use best shell available in site packages

Default
best
--pdb

use plain pdb

Default
None
--code

use stdlib's code.interact()

Default
None
--ptipython

use ptpython + ipython

Default
None
--ptpython

use ptpython

Default
None
--ipython

use ipython

Default
None
--bpython

use bpython

Default
None

Interactive usage

Run tmuxp shell to drop into a Python console with the current tmux server, session, window, and pane already bound. Pass arguments to select a specific one:

(Pdb) server
<libtmux.server.Server object at 0x7f7dc8e69d10>
(Pdb) server.sessions
[Session($1 your_project)]
(Pdb) session
Session($1 your_project)
(Pdb) session.name
'your_project'
(Pdb) window
Window(@3 1:your_window, Session($1 your_project))
(Pdb) window.name
'your_window'
(Pdb) window.panes
[Pane(%6 Window(@3 1:your_window, Session($1 your_project)))
(Pdb) pane
Pane(%6 Window(@3 1:your_window, Session($1 your_project)))

Running code directly

Pass -c to run a snippet and exit, much like python -c:

$ tmuxp shell -c 'python code'
../../_images/tmuxp-shell.gif

The same objects are in scope. Name a server, then a window, to narrow what the snippet sees:

$ tmuxp shell -c 'print(session.name); print(window.name)'
my_server
my_window

$ tmuxp shell my_server my_window -c 'print(window.name.upper())'
MY_WINDOW

Inside a tmux pane — or attached to the default server — the pane is in scope too:

$ tmuxp shell -c 'print(pane.id); print(pane.window.name)'
%2
my_window

Debugger integration

tmuxp shell supports PEP 553’s PYTHONBREAKPOINT and compatible debuggers, such as ipdb:

$ pip install --user ipdb

Inside a uv-managed project, add ipdb as a development dependency:

$ uv add --dev ipdb

For a pipx-style ad hoc install, run it through uvx:

$ uvx --from ipdb ipdb3 --help

$ env PYTHONBREAKPOINT=ipdb.set_trace tmuxp shell

Shell detection

tmuxp shell drops into the richest shell available in your site packages. Pick one yourself with a flag: