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
gdborlldb-dap) - Rust (via
gdborlldb-dap, selected explicitly) - Perl (via
perl -d) - Bash (via bash's own
DEBUGtrap; 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)
MIT License. Copyright 2026 by Al Danial.
- Debugs synchronous, asynchronous, multi-threaded, and multi-process Python,
with inspectors for
asynciotasks (including a task wait graph), threads, andmultiprocessing/concurrent.futureschildren - Attach to a running Python 3.11+ 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.mdfor headless and AI-assisted debugging - Runs 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:Debuggerintegration- 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
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
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 servertdb --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 serverSee the Quick Start page for many more examples, and the CLI Reference for every option.
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.