DRGN(1)

💖 NAME 💖

drgn — programmable debugger. Welcome to the DRGN(1) manual page, bestie! And yes, drgn is pronounced “dragon” 🐉 — it’s literally built for programmability.

✨ SYNOPSIS ✨

drgn [OPTION...]
drgn [OPTION...] SCRIPT [ARGUMENT...]
drgn [OPTION...] -e CODE [ARGUMENT...]

🦋 DESCRIPTION 🦋

okay so drgn (again: pronounced “dragon”) is a debugger with an emphasis on programmability. It gives you APIs for using the types, variables, and stack traces in a program or core dump from Python, which means easy, expressive scripting and more complex debugging. Slay.

Full documentation is available online at https://drgn.readthedocs.io/.

For in-program documentation, try help(drgn). iykyk 💅

💅 OPTIONS 💅

If no positional arguments are given (and -e is not given), then drgn runs in interactive mode: commands are read from the terminal. Relevant helpers are automatically imported. An empty string is prepended to sys.path.

If positional arguments are given (and -e is not given), then drgn runs in script mode: SCRIPT is executed with the given ARGUMENTs. Nothing is imported automatically. sys.argv[0] is set to SCRIPT and the remaining arguments are added to sys.argv. The parent directory of SCRIPT is prepended to sys.path.

• -e {CODE} — Evaluate the given code and exit. Relevant helpers are automatically imported. sys.argv[0] is set to -e and the remaining arguments are added to sys.argv. An empty string is prepended to sys.path.

👑 Program Selection 👑

One of these options may be given to specify what program to debug.

• -k, --kernel — Debug the running kernel. This is the default. main character energy 👑
• -c, --core {PATH} — Debug the given core dump.
• -p, --pid {PID} — Debug the running process with the given process ID.
• --qemu {ADDRESS} — Debug a QEMU guest over the QEMU Machine Protocol (QMP) at the given address, which may be a Unix domain socket path or a TCP address as host:port.

🎀 Debugging Symbols 🎀

• -s, --symbols {PATH} — Load debugging symbols from the given file. If the file does not correspond to a loaded executable, library, or module, then a warning is printed and it is ignored; see --extra-symbols for an alternative.

This option may be given more than once.

• --main-symbols — Only load debugging symbols for the main executable and those added with -s or --extra-symbols.
• --no-default-symbols — Don’t load any debugging symbols that were not explicitly added with -s or --extra-symbols.
• --extra-symbols {PATH} — Load additional debugging symbols from the given file, which is assumed not to correspond to a loaded executable, library, or module.

This option may be given more than once.

The following options correspond to drgn.Program.debug_info_options in the Python API.

• --try-symbols-by {METHOD[,METHOD...]} — Enable loading debugging symbols using the given methods. METHOD may be:
  • The name of a debugging information finder (standard, debuginfod, or any added by plugins).
  • module-name: if the name of a module looks like a filesystem path, try the file at that path.
  • build-id: search by build ID.
  • debug-link: search by debug link (e.g., .gnu_debuglink).
  • procfs: try /proc/pid/exe or /proc/pid/map_files.
  • embedded-vdso: try vDSO data saved in a core dump.
  • reuse: try reusing a previously used file.
  • supplementary: try finding supplementary files (e.g., .gnu_debugaltlink).
  • kmod=depmod: search using depmod metadata.
  • kmod=walk: search by walking kernel directories.
  • kmod=depmod-or-walk: search using depmod metadata if it is available or by walking kernel directories if depmod metadata does not exist.
  • kmod=depmod-and-walk: search using depmod metadata if it is available, then by walking kernel directories if depmod metadata does not exist or does not contain the desired module.

Multiple methods may be enabled by passing a comma-separated list. This option may be given more than once, in which case the lists will be combined.

• --no-symbols-by {METHOD[,METHOD...]} — Disable loading debugging symbols using the given methods. METHOD may be the name of a debugging information finder, module-name, build-id, debug-link, procfs, embedded-vdso, reuse, supplementary, or kmod.

Multiple methods may be disabled by passing a comma-separated list. This option may be given more than once, in which case the lists will be combined.

🌸 Debugging Symbol Directories 🌸

These options correspond to drgn.DebugInfoOptions.directories in the Python API.

• --debug-directory {PATH} — Search for debugging symbols in the given directory.

By default, these directories are used for searches by build ID, debug link, for supplementary files, and for kernel files.

This option may be given more than once to search in multiple directories.

• --no-default-debug-directories — Don’t search for debugging symbols in the standard directories or those added by plugins.

These options correspond to drgn.DebugInfoOptions.debug_link_directories in the Python API.

• --debug-link-directory {PATH} — Search for debugging symbols by debug link in the given directory.

$ORIGIN (or ${ORIGIN}) is replaced with the absolute path of the directory containing the loaded file.

This option may be given more than once to search in multiple directories.

• --no-default-debug-link-directories — Don’t search for debugging symbols by debug link in the standard directories or those added by plugins.

These options correspond to drgn.DebugInfoOptions.kernel_directories in the Python API.

• --kernel-directory {PATH} — Search for the kernel image and loadable kernel modules in the given directory.

This option may be given more than once to search in multiple directories.

• --no-default-kernel-directories — Don’t search for the kernel image and loadable kernel modules in the standard directories or those added by plugins.

🦋 Logging 🦋

• --log-level {\{debug,info,warning,error,critical,none\}} — Log messages of at least the given level to standard error. The default is warning.
• -q, --quiet — Don’t print any logs or download progress. This is equivalent to --log-level none.

⭐ Generic Information ⭐

• -h, --help — Show a help message and exit.
• --version — Show drgn’s version information and exit.

🎀 COPYRIGHT 🎀

Omar Sandoval

---

💖 Cute sign-off: this DRGN(1) page is serving version 0.3.0, dated Oct 22, 2026. Bye bestie, go debug something iconic! 🫶✨