Page moved
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
CPython tips
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
, 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_<instruction>, for example, TARGET_LOAD_CONST. You can then set a breakpoint with a command like:
(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 savebreakpoints 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