GDB support#

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 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_<instruction>, e.g., 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 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