notebook-terminal 0.3.0

A cross-platform PTY/ConPTY terminal for Jupyter with bundled xterm.js

Notebook Terminal

Notebook Terminal embeds a real PTY/ConPTY terminal in Jupyter notebooks and provides reusable terminal sessions for Flask and Django.

Version 0.4.0 removes the anywidget dependency. The notebook frontend uses bundled xterm.js plus standard ipywidgets channels, so it requires no JupyterLab extension, administrator installation, HTTP server, iframe, WebSocket, CDN, or internet connection.

Requirements

• Python 3.9+
• ipywidgets 8+
• Windows: pywinpty
• Linux/macOS: the standard POSIX PTY implementation
• A trusted notebook that permits JavaScript output

Installation

python -m pip install notebook-terminal

For an offline installation, download the wheel and its dependencies on another computer and install them with --no-index --find-links.

Jupyter quick start

from notebook_terminal import terminal

term = terminal(height=450, interactive=True)

The initial banner, prompt, username, host name, and working directory are generated by the real shell process. Nothing such as PS C:\\Users\\Admin> is hardcoded.

term.run("python --version")
term.run("git status")

Read-only mode:

term = terminal(interactive=False)
term.run("python script.py")

Python execution and rich output

term.run_python("""
import pandas as pd
import matplotlib.pyplot as plt

frame = pd.DataFrame({"x": [1, 2, 3], "y": [3, 1, 4]})
display(frame)
plt.plot(frame["x"], frame["y"])
plt.show()
""", rich_output=True, clear_previous=True)

Rich output tabs support DataFrames, images, HTML, Plotly, and standard Jupyter widgets created with run_kernel().

Status output

term.success("Code completed successfully")
term.info("Starting")
term.warning("Check configuration")
term.error("Operation failed")

These messages are emitted to the display output channel and are never sent to PowerShell/Bash stdin.

History and process control

term.history()
term.last_command
term.rerun()
term.clear_history()
term.interrupt()
term.restart()
term.wait_for("ready", timeout=10)
term.wait_until_idle(timeout=30)
term.clear(clear_tabs=True)

Clipboard

• Ctrl+C copies selected terminal text.
• Ctrl+C without a selection interrupts the process.
• Ctrl+V pastes in interactive mode.

Flask and Django

The framework-independent TerminalSession and WebSocket adapters remain available:

from notebook_terminal.web import manager

session_id, session = manager.create(cwd=".", interactive=True)
session.run("python --version")

Install optional integrations:

python -m pip install "notebook-terminal[flask]"
python -m pip install "notebook-terminal[django]"

Flask uses flask-sock; Django uses Channels. Both reuse the same terminal session backend and xterm-compatible message protocol.

How the Jupyter bridge works

The notebook frontend is made from:

1. a real PTY/ConPTY TerminalSession,
2. bundled xterm.js and CSS,
3. three hidden standard ipywidgets.Textarea channels,
4. JavaScript output that connects xterm.js to those standard widgets,
5. a kernel dispatcher that performs widget updates on the kernel event loop.

This avoids AnyModel, custom JupyterLab extensions, version registration errors, and the shell_parent ContextVar error caused by mutating widgets directly from PTY reader threads.

Limitations

Jupyter must allow trusted JavaScript output. Some heavily restricted notebook hosts may disable JavaScript output entirely; that cannot be bypassed by a Python package without administrator support. Standard ipywidgets must also work.

Build

python -m pip install build twine pytest
python -m pytest
python -m build
python -m twine check dist/*

License

MIT