Python Commands (Debugging with GDB)

#### 23.3.1 Python Commands ¶

GDB provides two commands for accessing the Python interpreter, and one related setting:

`python-interactive [command]` ¶
`pi [command]`

  Without an argument, the `python-interactive` command can be used to start an interactive Python prompt. To return to GDB, type the `EOF` character (e.g., `Ctrl-D` on an empty prompt).

  Alternatively, a single-line Python command can be given as an argument and evaluated. If the command is an expression, the result will be printed; otherwise, nothing will be printed. For example:

      (gdb) python-interactive 2 + 3
      5

`python [command]` ¶
`py [command]`

  The `python` command can be used to evaluate Python code.

  If given an argument, the `python` command will evaluate the argument as a Python command. For example:

      (gdb) python print 23
      23

  If you do not provide an argument to `python`, it will act as a multi-line command, like `define`. In this case, the Python script is made up of subsequent command lines, given after the `python` command. This command list is terminated using a line containing `end`. For example:

      (gdb) python
      >print 23
      >end
      23

`set python print-stack` ¶

  By default, GDB will print only the message component of a Python exception when an error occurs in a Python script. This can be controlled using `set python print-stack`: if `full`, then full Python stack printing is enabled; if `none`, then Python stack and message printing is disabled; if `message`, the default, only the message component of the error is printed.

`set python ignore-environment [on|off]` ¶

  By default this option is ‘`off`’, and, when GDB initializes its internal Python interpreter, the Python interpreter will check the environment for variables that will effect how it behaves, for example `PYTHONHOME`, and `PYTHONPATH`18.

  If this option is set to ‘`on`’ before Python is initialized then Python will ignore all such environment variables. As Python is initialized early during GDB’s startup process, then this option must be placed into the early initialization file (see Initialization Files) to have the desired effect.

  This option is equivalent to passing `-E` to the real `python` executable.

`set python dont-write-bytecode [auto|on|off]` ¶

  When this option is ‘`off`’, then, once GDB has initialized the Python interpreter, the interpreter will byte-compile any Python modules that it imports and write the byte code to disk in `.pyc` files.

  If this option is set to ‘`on`’ before Python is initialized then Python will no longer write the byte code to disk. As Python is initialized early during GDB’s startup process, then this option must be placed into the early initialization file (see Initialization Files) to have the desired effect.

  By default this option is set to ‘`auto`’. In this mode, provided the `python ignore-environment` setting is ‘`off`’, the environment variable `PYTHONDONTWRITEBYTECODE` is examined to see if it should write out byte-code or not. `PYTHONDONTWRITEBYTECODE` is considered to be off/disabled either when set to the empty string or when the environment variable doesn’t exist. All other settings, including those which don’t seem to make sense, indicate that it’s on/enabled.

  This option is equivalent to passing `-B` to the real `python` executable.

It is also possible to execute a Python script from the GDB interpreter:

`source `script-name``

  The script name must end with ‘`.py`’ and GDB must be configured to recognize the script language based on filename extension using the `script-extension` setting. See Extending GDB.

The following commands are intended to help debug GDB itself:

`set debug py-breakpoint on|off` ¶
`show debug py-breakpoint`

  When ‘`on`’, GDB prints debug messages related to the Python breakpoint API. This is ‘`off`’ by default.

`set debug py-unwind on|off` ¶
`show debug py-unwind`

  When ‘`on`’, GDB prints debug messages related to the Python unwinder API. This is ‘`off`’ by default.

#### Footnotes

##### (18)

See the ENVIRONMENT VARIABLES section of `man 1 python` for a comprehensive list.