Install & Compatibility
Where this runs
tested against v0.11.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.078s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.072s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GdbController
✓ from pygdbmi.gdbcontroller import GdbController
parse_response
✓ from pygdbmi.gdbmiparser import parse_response
NoGdbProcessError
✓ Removed in v0.10.0.0
✗ from pygdbmi.constants import NoGdbProcessError
`NoGdbProcessError` was removed as part of the `GdbController` API changes in v0.10.0.0. Handlers for GDB process issues should now rely on `subprocess.CalledProcessError` or similar standard Python exceptions for subprocess management.
This quickstart demonstrates how to use `GdbController` to interact with a GDB subprocess programmatically, including loading a binary, setting a breakpoint, running, and continuing execution. It also shows how to directly parse a raw GDB MI output string using `gdbmiparser.parse_response`. A simple C program is compiled and used as the debug target for the demonstration.
from pygdbmi.gdbcontroller import GdbController
from pprint import pprint
import os
import subprocess
import shutil
# NOTE: This example assumes 'make' and 'gdb' are available in your PATH.
# Create a dummy C program for debugging
if not os.path.exists('sample_app'):
os.makedirs('sample_app')
with open('sample_app/main.c', 'w') as f:
f.write('int main() { int x = 1; x++; return 0; }')
if shutil.which('gcc') and shutil.which('make'):
subprocess.run(['gcc', 'main.c', '-o', 'pygdbmiapp', '-g'], cwd='sample_app', check=True)
binary_path = os.path.abspath('sample_app/pygdbmiapp')
else:
print("Warning: 'gcc' or 'make' not found. Quickstart will only demonstrate parsing.")
binary_path = None
gdbmi = GdbController()
try:
if binary_path:
print(f"\nDebugging: {binary_path}")
# Load the binary
responses = gdbmi.write(f"-file-exec-and-symbols {binary_path}")
print("Load binary response:")
pprint(responses)
# Set a breakpoint at main
responses = gdbmi.write("-break-insert main")
print("Breakpoint response:")
pprint(responses)
# Run the program
responses = gdbmi.write("-exec-run")
print("Run response:")
pprint(responses)
# Continue to finish
responses = gdbmi.write("-exec-continue")
print("Continue response:")
pprint(responses)
# Example of parsing raw MI output
print("\nParsing raw GDB MI output:")
raw_mi_output = '^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",addr="0x08048564",func="main",file="myprog.c",fullname="/home/myprog.c",line="68",thread-groups=["i1"],times="0"}'
parsed_response = gdbmi.gdbmiparser.parse_response(raw_mi_output)
pprint(parsed_response)
finally:
# Ensure gdb process is terminated
gdbmi.exit()
print("\nGDB process exited.")
# Clean up dummy app
shutil.rmtree('sample_app', ignore_errors=True)
pygdbmi --version
Debug
Known issues
breakingThe `GdbController` class API changed significantly in version 0.10.0.0. The constructor now expects `command: Optional[List[str]]` and `time_to_check_for_additional_output_sec: Optional[int]]`. Several methods like `GdbController.verify_valid_gdb_subprocess()` were removed, and the `NoGdbProcessError` exception was also removed.fixReview your `GdbController` instantiation and method calls. Update to the new constructor signature and remove calls to deprecated methods and exception handling for `NoGdbProcessError`. For Python 3.5, upgrade your Python version as support was dropped.
affects: 0.10.0.0+
breakingSupport for Python 3.5 was dropped in `pygdbmi` v0.10.0.0, and support for Python 3.6 was dropped in v0.10.0.2.fixEnsure your project is running on Python 3.7 or newer to use `pygdbmi` versions 0.10.0.2 and above. Python 3.9 and 3.10 are explicitly supported from v0.10.0.2.
affects: 0.10.0.0+
breakingThe `pygdbmi.IoManager.make_non_blocking` function was removed from the public API in version 0.11.0.0 as it was considered an internal utility not meant for public consumption.fixRemove any direct calls to `pygdbmi.IoManager.make_non_blocking` from your code. This function was an internal detail and should not have been used directly.
affects: 0.11.0.0+
gotchaWhen using GDB versions 8.1 and newer, the output from the `run` command might be split into multiple parts. This can cause `pygdbmi` to only catch the initial part, leading to `GdbTimeOutError` if subsequent calls to `get_gdb_response()` are not handled correctly to fetch all parts of the response.fixBe aware of GDB's output behavior with newer versions. If encountering timeouts after a `run` command, you may need to adjust `time_to_check_for_additional_output_sec` in `GdbController` or implement more robust polling for `get_gdb_response()` to ensure all output is consumed.
affects: All versions, with GDB 8.1+
gotchaTo ensure GDB outputs machine-readable interface (MI) format, it must be launched with the `--interpreter=mi2` flag. If this flag is omitted, `pygdbmi` will receive standard console output which it cannot reliably parse into structured data.fixAlways pass `--interpreter=mi2` as part of the GDB command list when initializing `GdbController`, e.g., `GdbController(command=['gdb', '--interpreter=mi2'])`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pygdbmi'
The `pygdbmi` package is not installed in the Python environment being used.
fixInstall the library using pip: `pip install pygdbmi`
pygdbmi.gdbcontroller.GdbTimeoutError: Did not get response from gdb after X seconds
GDB did not respond to a command within the allotted timeout period, often because the debugged program is still running, paused, or the timeout is too short for the operation.
fixIncrease the `timeout_sec` parameter in the `write()` method (e.g., `gdbmi.write('command', timeout_sec=5)`) or ensure GDB is in a state to respond. If the debugee is printing a lot of output, this can also cause delays that lead to timeouts. ValueError: 'gdb' executable could not be resolved from "gdb"
The `gdb` executable is not found in the system's PATH environment variable or at the specific path provided to the `GdbController`.
fixEnsure GDB is installed and its executable is accessible via the system's PATH, or provide the full path to the GDB executable when initializing `GdbController`: `gdbmi = GdbController(command=['/usr/bin/gdb', '--interpreter=mi2'])`
ImportError: cannot import name 'POINTER' from 'ctypes.wintypes'
This error typically occurs in older versions of `pygdbmi` (e.g., 0.7.4.2) on Windows due to an incompatibility with `ctypes.wintypes` in certain Python versions.
fixUpgrade to the latest version of `pygdbmi` (`pip install --upgrade pygdbmi`), as this issue was addressed in subsequent releases.
ModuleNotFoundError: No module named 'pygdbmi.constants'
This import error indicates that the code is attempting to import `GdbTimeoutError` (or other constants) from a module path that no longer exists due to API changes in `pygdbmi` versions.
fixUpdate your import statement for `GdbTimeoutError` to `from pygdbmi.gdbcontroller import GdbTimeoutError` and upgrade `pygdbmi` to a recent version.
Upgrade
Version history
0.11.0.0latest on PyPI · released Jan 29, 2023
Audit
Dependencies
No dependency data recorded yet.