---
name: "drgn"
section: "1"
platform: "linux"
package: "python3-drgn"
version: "0.0.31-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/drgn"
---

# drgn(1)

programmable debugger

## NAME

drgn - programmable debugger

## SYNOPSIS

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

## DESCRIPTION

**drgn** (pronounced "dragon") is a debugger with an emphasis on programmability. It provides APIs for using the types, variables, and stack traces in a program or core dump from Python, allowing for easy, expressive scripting and more complex debugging.

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

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

## 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 *ARGUMENT*s. 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.

- **-c, --core *PATH***

  Debug the given core dump.

- **-p, --pid *PID***

  Debug the running process with the given process ID.

### 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.

- **--debug-directory *PATH***

  Search for debugging symbols by build ID and debug link in the given directory.

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

- **--no-default-debug-directories**

  Don't search for debugging symbols by build ID and debug link in the standard directories or those added by plugins.

- **--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