Using the Python debugger (pdb)
Keywords: manual

Subsections

- Running entire programs via `pdb`
- Automatic invocation of `pdb` on exceptions

#
Using the Python debugger (`pdb`)

## Running entire programs via `pdb`

`pdb`, the Python debugger, is a powerful interactive debugger which allows you to step through code, set breakpoints, watch variables, etc. IPython makes it very easy to start any script under the control of `pdb`, regardless of whether you have wrapped it into a ``main()'` function or not. For this, simply type ``%run -d myscript'` at an IPython prompt. See the `%run` command's documentation (via ``%run?'` or in Sec. 6.2) for more details, including how to control where `pdb` will stop execution first.

For more information on the use of the `pdb` debugger, read the included `pdb.doc` file (part of the standard Python distribution). On a stock Linux system it is located at `/usr/lib/python2.3/pdb.doc`, but the easiest way to read it is by using the `help()` function of the `pdb` module as follows (in an IPython prompt):

`In [1]: import pdb`
`In [2]: pdb.help()`

This will load the `pdb.doc` document in a file viewer for you automatically.

## Automatic invocation of `pdb` on exceptions

IPython, if started with the `-pdb` option (or if the option is set in your rc file) can call the Python `pdb` debugger every time your code triggers an uncaught exception6. This feature can also be toggled at any time with the `%pdb` magic command. This can be extremely useful in order to find the origin of subtle bugs, because `pdb` opens up at the point in your code which triggered the exception, and while your program is at this point `dead', all the data is still available and you can walk up and down the stack frame and understand the origin of the problem.

Furthermore, you can use these debugging facilities both with the embedded IPython mode and without IPython at all. For an embedded shell (see sec. 9), simply call the constructor with ``-pdb'` in the argument string and automatically `pdb` will be called if an uncaught exception is triggered by your code.

For stand-alone use of the feature in your programs which do not use IPython at all, put the following lines toward the top of your `main' routine:

`import sys,IPython.ultraTB`
`sys.excepthook = IPython.ultraTB.FormattedTB(mode=`Verbose', color_scheme=`Linux', call_pdb=1)`

The `mode` keyword can be either ``Verbose'` or ``Plain'`, giving either very detailed or normal tracebacks respectively. The `color_scheme` keyword can be one of ``NoColor'`, ``Linux'` (default) or ``LightBG'`. These are the same options which can be set in IPython with `-colors` and `-xmode`.

This will give any of your programs detailed, colored tracebacks with automatic invocation of `pdb`.