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