Information on debugging CPython using GDB is now in the main Python documentation, since it is relevant for C extension modules as well. Please read it first: Debugging C API extensions and CPython Internals with GDB
This document includes a few additional tips that are useful specifically for debugging CPython internals.
Breaking at labels#
You will most often set breakpoints at the start of functions, but
this approach is less helpful when debugging the runtime virtual
machine, since the main interpreter loop function,
_PyEval_EvalFrameDefault, is well over 4,000 lines long as of Python 3.12.
Fortunately, among the many ways to set breakpoints,
you can break at C labels, such as those generated for computed gotos.
If you are debugging an interpreter compiled with computed goto support
(generally true, certainly when using GCC), each instruction will be
prefaced with a label named
TARGET_LOAD_CONST. You can then set a breakpoint with a command
(gdb) break ceval.c:_PyEval_EvalFrameDefault:TARGET_LOAD_CONST
Add commands, save to a file, then reload in future sessions without worrying that the starting line number of individual instructions change over time.
Saving and loading breakpoints#
With extended exposure to particular parts of the Python runtime, you
might find it helpful to define a routine set of breakpoints and
commands to execute when they are hit.
For convenience, save your breakpoints to a file and load them in future
sessions using the
save breakpoints command:
(gdb) save breakpoints python.brk
You can edit the file to your heart’s content, then load it in a later session:
(gdb) source python.brk