Skip to content

Last updated：2026-10-12

GDB Python Extension Debugging

0.Introduction

Debugging is an indispensable part of software development, and GDB (the GNU Debugger), as a powerful debugging tool, is widely used among developers. Besides the traditional command-line debugging features, GDB also provides a Python GDB library that allows developers to extend and enhance their debugging capabilities using the Python language. This article introduces how to use the Python GDB library inside GDB, demonstrating its powerful debugging features and use cases.

Before starting, make sure Python and GDB are correctly installed and that the Python version is compatible with GDB. Then, install the Python GDB library by following these steps:

a. Run gdb on the command line to open GDB.

b. Type the python command to enter GDB's Python interpreter.

c. Run import gdb; if no error is reported, the Python GDB library is correctly installed.

(gdb) python
>import gdb
>end

While debugging with gdb, we often want to inspect variables with complex structures, such as the List structure in PostgreSQL, which can hold anything — what exactly is inside it is hard to print directly. That is where Python scripts come in for our daily development, as in the example below:

(gdb) tl
TargetEntry [resno=1 resname="sum"]
    Aggref [aggfnoid=2107 aggtype=1700 aggtranstype=2281 aggstar=false aggvariadic=false aggkind=110 'n' agglevelsup=0 aggsplit=AGGSPLIT_FINAL_DESERIAL aggno=0 aggtransno=0 agg_expr_id=0]

1.Hello python gdb

We can run some Python operations inside gdb, for example: print, as shown below:

scssCopy code
(gdb) python
> print(1+2)
> end
3
(gdb) end
This command cannot be used at the top level.

In this example, we entered GDB's Python interpreter and executed a simple Python statement, print(1+2), whose result is 3.

Another example is that we can directly type python xxxx to run it.

scssCopy code
(gdb) python f = 2
(gdb) python print(f)
2

In this example, we defined a variable f with a Python statement inside GDB and printed its value, with the result 2.

2.In Practice: How to Write One?

The key point is how do we write these scripts, so that we can conveniently print our own data? What follows is the hands-on part. The code and materials related to this section will be published in the Knowledge Planet community — stay tuned:

struct Point {
    int x;
    int y;
};

Now, given a Point struct, I want to print it out with a script — how do we do that?

The logic is very simple: read the struct, then print it.

import gdb

def print_point(point):
    print(f"Point: x={point['x']}, y={point['y']}")

def print_person(person):
    age = person['age']
    print(f"Person: age={age}")

class PrintCppStruct(gdb.Command):
    def __init__(self):
        super(PrintCppStruct, self).__init__("print_cpp_struct", gdb.COMMAND_USER)

    def invoke(self, arg, from_tty):
        try:
            cl = gdb.parse_and_eval(arg)
            if cl.type.code == gdb.TYPE_CODE_STRUCT and str(cl.type) == 'Point':
                print_point(cl)
            elif cl.type.code == gdb.TYPE_CODE_STRUCT and str(cl.type) == 'Person':
                print_person(cl)
            else:
                print("Unknown C++ structure type.")
        except gdb.error as e:
            print(f"Error: {e}")

PrintCppStruct()

How to use it?

Just source it:

(gdb) source print.py

In this example, we used the source command to load a Python script named print.py into GDB.

(gdb) print_cpp_struct myPoint
Point: x=10, y=20

In this example, we used a custom command print_cpp_struct inside GDB, which printed the value of a C++ struct named myPoint via the Python GDB library.

By using the Python GDB library inside GDB, developers can leverage the power of Python to extend and enhance their debugging capabilities. It provides a rich API and flexible scripting, making the debugging process more efficient and convenient. Whether it is automating debugging tasks, data analysis and visualization, or dynamically modifying program behavior, the Python GDB library offers developers abundant choices and flexibility. I hope this article helps you better understand and apply the Python GDB library, and improves your debugging skills and development efficiency.

Comments