textual-debugger

textual-debugger (the package) provides tdb (the command-line tool and module), a full-featured terminal-based debugger for Python and other languages with a Debug Adapter Protocol (DAP) implementation. In addition to Python, tdb comes with built-in support for

• C, C++, Fortran (via gdb or lldb-dap)
• Rust (via gdb or lldb-dap, selected explicitly)
• Perl (via perl -d)
• Bash (via bash's own DEBUG trap; bash ≥ 4.4)
• Tcsh (via source instrumentation of a stock tcsh)
• Ruby (via the debug gem's rdbg; debug ≥ 1.9)
• OCaml (native via lldb-dap/gdb, bytecode via ocamlearlybird)
• Go (via Delve's dlv dap)
• PowerShell 7 (via PowerShell Editor Services; Linux/macOS, Windows experimental)

Documentation: https://textual-debugger.readthedocs.io/ (also available offline with tdb --doc, or as plain text with tdb --doc-text)

• PyPI: https://pypi.org/project/textual-debugger/
• GitHub: https://github.com/AlDanial/tdb

MIT License. Copyright 2026 by Al Danial.

Highlights

• Debugs synchronous, asynchronous, multi-threaded, and multi-process Python, with inspectors for asyncio tasks (including a task wait graph), threads, and multiprocessing / concurrent.futures children
• Attach to a running Python (3.11+), C/C++, Go, Rust, or OCaml program by PID, with no preparation
• Remote attach to Python, Perl, Ruby, Rust, C/C++, and Go programs
• JSON-RPC server, MCP (v2) server, and a SKILL.md for headless and AI-assisted debugging
• Can run the debuggee in an external terminal to debug TUI applications
• Post-mortem exception hook and live breakpoint hooks (tdb.breakpoint() and its counterparts in Perl, Ruby, Go, C/C++/Fortran, Rust, and OCaml)
• pytest --pdbcls=tdb.pytest_debugger:Debugger integration
• Run mode (--run) to attach the TUI to a running job on Ctrl-C, and eval mode (--eval) to print expressions at chosen lines without the TUI
• Entirely keyboard-driven, with vim, emacs, and Notepad-style keybindings; mouse support in graphical environments

Gallery

Videos:

• tdb basics views, keybindings, breakpoints, stepping, variable modification, call stack
• asyncio tasks inspect asyncio tasks and their wait graph; code mod to allow pause
• threads and processes inspect variables and call stacks in multiple threads and processes
• external terminal run the debuggee in a separate terminal--ideal for debugging TUI applications

Installation

uv pip install textual-debugger        # or: pip install textual-debugger
uvx --from textual-debugger tdb my_program.py   # run without installing
pip install "textual-debugger[mcp]"    # add the optional MCP server

Quick Start

tdb --doc                        # full documentation in a terminal Markdown viewer
tdb --info                       # versions and locations of tdb, its config, and every debugger it would use
tdb my_program.py arg1 arg2      # debug a Python program (stops at the first line)
tdb -k 20 -k module.py:14 my_program.py   # run to breakpoints
tdb -k module.py:27 --if "a > 7" my_program.py   # ... stopping only when a > 7
tdb ./myprog                     # debug a native executable built with -g
tdb script.pl                    # ... or a Perl, Bash, Tcsh, Ruby, PowerShell script
tdb -a 12345                     # attach to a running Python program by PID
tdb -r remotehost:5678           # attach to a remote debugpy server

See the Quick Start page for many more examples, and the CLI Reference for every option.

Acknowledgments

tdb is built with Will McGugan's textual and Microsoft's debugpy, and was inspired by Andreas Klöckner's pudb. See About for the full acknowledgments.