使用 GDB 调试 Python

11月 27, 2025

使用 GDB 调试 Python#

1. 引言#

GDB (GNU Debugger) 是一个功能强大的命令行调试工具，常用于调试 C/C++ 程序。但你知道吗？GDB 也可以用于调试 Python 程序，特别是在以下场景中：

• Python 解释器崩溃时分析核心转储
• 调试 Python 扩展模块（C/C++ 编写）
• 分析 Python 程序的性能瓶颈
• 调试 Python 解释器本身

本文将详细介绍如何使用 GDB 调试 Python 程序，从基础配置到高级技巧，帮助你掌握这一强大的调试方法。

2. 准备工作#

2.1 安装 GDB#

在大多数 Linux 发行版中，GDB 可以通过包管理器安装：

# Debian/Ubuntu
apt-get update && apt-get install -y gdb

# CentOS/RHEL
yum install -y gdb

# Fedora
dnf install -y gdb

# macOS（需要安装 Xcode Command Line Tools）
xcode-select --install

2.2 安装 Python 调试符号#

为了获得更好的调试体验，需要安装 Python 的调试符号包：

# Debian/Ubuntu
apt-get install -y python3-dbg

# CentOS/RHEL
yum install -y python3-debuginfo

# macOS
# macOS 上的 Python 调试符号通常随 Xcode 一起安装

2.3 验证安装#

安装完成后，验证 GDB 和 Python 调试环境：

# 检查 GDB 版本
gdb --version

# 检查 Python 调试符号
gdb python3 -ex "info sharedlibrary" -ex quit

3. 基本概念#

3.1 Python 解释器的工作原理#

Python 是一种解释型语言，其执行过程分为两个阶段：

1. 编译阶段：将 Python 代码编译为字节码（.pyc 文件）
2. 执行阶段：Python 解释器（CPython）执行字节码

当使用 GDB 调试 Python 程序时，我们实际上是在调试 CPython 解释器进程，通过 GDB 的 Python 扩展来访问 Python 程序的内部状态。

3.2 GDB 的 Python 扩展#

CPython 内置了 GDB 扩展，提供了一系列 GDB 命令来调试 Python 程序。这些命令位于 /usr/lib/python3.x/libpython3.x.so.1.0-gdb.py（具体路径可能因系统而异）。

4. 基本命令#

4.1 启动 GDB 调试 Python 程序#

# 方式 1：直接启动 Python 程序并附加 GDB
gdb --args python3 your_script.py

# 方式 2：先启动 Python 程序，再用 GDB 附加
python3 your_script.py &
pgrep -f "python3 your_script.py"  # 获取 PID
gdb python3 <PID>

# 方式 3：调试 Python 解释器崩溃生成的核心转储
gdb python3 core.12345

4.2 常用 GDB 命令#

4.3 常用 Python 特定命令#

CPython 提供了一系列专用的 GDB 命令，用于调试 Python 程序：

5. 实际案例#

5.1 调试简单 Python 脚本#

创建一个简单的 Python 脚本 test.py：

#!/usr/bin/env python3

def factorial(n):
    if n == 0:
        return 1
    else:
        return n * factorial(n-1)

result = factorial(5)
print(f"Factorial of 5 is {result}")

使用 GDB 调试该脚本：

gdb --args python3 test.py

在 GDB 提示符下执行以下命令：

# 设置断点在 factorial 函数
break factorial

# 启动程序
run

# 查看 Python 调用栈
py-bt

# 查看当前 Python 代码
py-list

# 查看局部变量
py-locals

# 单步执行
next

# 继续执行到函数返回
finish

# 打印结果
py-print result

# 退出 GDB
quit

5.2 调试 Python 解释器崩溃#

假设我们有一个导致 Python 解释器崩溃的脚本 crash.py：

#!/usr/bin/env python3

# 导入一个有问题的扩展模块
import crash_module

# 调用导致崩溃的函数
crash_module.crash()

当这个脚本运行时，Python 解释器会崩溃并生成核心转储文件。使用 GDB 分析核心转储：

gdb python3 core.12345

在 GDB 提示符下执行：

# 查看完整的 C 调用栈
backtrace full

# 查看 Python 调用栈
py-bt

# 查看导致崩溃的 Python 代码
py-list

# 分析崩溃原因
info registers

6. 高级技巧#

6.1 调试多线程 Python 程序#

对于多线程 Python 程序，可以使用以下命令进行调试：

# 显示所有 Python 线程
py-threads

# 切换到指定 Python 线程
thread <thread_num>

# 显示当前线程的 Python 调用栈
py-bt

# 在所有线程上设置断点
break <location> thread all

6.2 调试 Python 扩展模块#

调试 Python 扩展模块时，可以将扩展模块的源代码与 GDB 关联：

# 添加源代码搜索路径
directory /path/to/extension/source

# 设置断点在扩展模块的函数上
break extension_function

# 查看扩展模块的共享库
info sharedlibrary <extension_name>

6.3 使用 GDB 脚本自动化调试#

可以编写 GDB 脚本自动化重复的调试任务。创建一个 debug.gdb 文件：

# debug.gdb
file python3
set args test.py
break factorial
run
py-bt
py-locals
quit

使用该脚本：

gdb -x debug.gdb

6.4 分析 Python 程序的性能#

GDB 可以用于分析 Python 程序的性能瓶颈：

# 启动程序
run

# 暂停程序
Ctrl+C

# 查看当前调用栈
py-bt

# 继续执行
continue

通过多次暂停和查看调用栈，可以找出程序花费时间最多的地方。

7. 常见问题#

7.1 GDB 无法找到 Python 调试符号#

问题：启动 GDB 时显示 “Missing separate debuginfos” 或 “No debugging symbols found”

解决方案：

# 安装 Python 调试符号包
apt-get install -y python3-dbg  # Debian/Ubuntu
yum install -y python3-debuginfo  # CentOS/RHEL

7.2 GDB 无法识别 Python 特定命令#

问题：执行 py-bt 等命令时显示 “Undefined command: “py-bt””

解决方案：

# 手动加载 Python 调试扩展
so /usr/lib/python3.x/libpython3.x.so.1.0-gdb.py

7.3 调试时 Python 代码显示不全#

问题：使用 py-list 命令时，Python 代码显示不完整

解决方案：

# 设置 Python 代码显示的行数
set python print-stack 20

8. 总结#

使用 GDB 调试 Python 程序是一种强大的调试方法，特别适合处理 Python 解释器崩溃、调试扩展模块和分析性能瓶颈等场景。虽然 GDB 的学习曲线较陡，但掌握它将为你提供深入理解 Python 内部工作原理的能力。

通过本文的介绍，你应该已经掌握了：

• 如何配置 GDB 调试 Python 环境
• 常用的 GDB 命令和 Python 特定命令
• 如何调试简单 Python 脚本和崩溃的 Python 程序
• 多线程调试、扩展模块调试和性能分析等高级技巧
• 常见问题的解决方案

GDB 是 Python 调试工具链中的重要补充，与 pdb、py-spy 等工具配合使用，可以帮助你解决各种复杂的 Python 调试问题。

9. 参考资料#

• GDB 官方文档
• Python 官方 GDB 调试指南
• Debugging Python with GDB
• CPython GDB 扩展源码