tmuxp shell

Launch an interactive Python shell with libtmux objects pre-loaded. Similar to Django’s shell command, this provides quick access to your tmux server, sessions, windows, and panes for scripting and debugging.

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

Directly enter commands

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

Interactive usage

Launch into a Python console with libtmux objects. Compare to django’s shell.

Automatically preloads current tmux server, session, window pane. Pass additional arguments to select a specific one of your choice:

(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)))

Debugger integration

Supports PEP 553’s PYTHONBREAKPOINT and compatible debuggers, for instance ipdb:

$ pip install --user ipdb

Inside a uv-managed project you can 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

Code execution

You can also pass in python code directly, similar to python -c, do this via tmuxp -c:

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

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

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

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

Assuming inside a tmux pane or one is attached on default server:

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

Shell detection

tmuxp shell detects the richest shell available in your site packages, you can also pick your shell via args:

  • --pdb: Use plain old breakpoint() (python 3.7+) or pdb.set_trace

  • --code: Drop into code.interact, accepts --use-pythonrc

  • --bpython: Drop into bpython

  • --ipython: Drop into ipython

  • --ptpython: Drop into ptpython, accepts --use-vi-mode

  • --ptipython: Drop into ipython + ptpython, accepts --use-vi-mode