Norm Matloff's Introduction to the Winpdb Python Debugging Tool (not just for Windows!)



The original author of Winpdb, Nir Aides, no longer supports the package. It has been taken over by Philippe Fremy as Winpdb Reborn.

The software is now packaged as a Wheel (.whl) file, which is actually .zip. I recommend simply unzipping it and running it directly if you are not well-versed on pip, Python library directories and so on.

About Winpdb and RPDB2:

The Winpdb package, by Nir Aides, is an excellent Python debugger. It is especially nice because it can handle the debugging of threads- and curses-based code. It is a remote debugger, meaning that it connects through the network to a remote site (which can be the same machine at which it is invoked, which is typical).

RPDB2 is text-based, while Winpdb is a GUI front end to RPDB2.

RPDB2 and Winpdb run on Linux, Windows and Mac systems. Winpdb requires the wxPython package, which is also freely downloadable for both systems. (My tutorial here is somewhat Linux-centric, but for the most part applies to Windows as well.)

Where to obtain them:

You can get them from Winpdb home page. Download the Winpdb package, which includes RPDB2.


If you just intend to use the non-GUI form, i.e. just use RPDB2, you don't need to install wxPython. Just go straight to RPDB2 section below.

Actually, you need not formally install. Just unpack as below, and then each time you debug your source file, run the debugger, say residing in directory /a/b/c/ by typing

python /a/b/c/ arg0 arg1 ...

You could even make a shell alias for this.

To formally install:

Unpack the .gz Winpdb package that you download, and enter the newly-created directory. From a shell window, type

python install -f

If you get an installation error, you need to install wxPython. I recommend that you let your OS do the work for you. In Fedora Core Linux, for instance, type

yum install wxPython

from a shell window. With Ubuntu Linux, use

sudo apt-get install python-wxgtk2.8

(or a later version number).

If you get a runtime error when you try Winpdb like "No module named winpdb," then you either have a permissions or a path problem.

Using Winpdb:

Like any software, Winpdb has a lot of bells and whistles. Here I only cover the basics.

Winpdb startup:

Say you have a script to debug, with command-line arguments arg0, arg1 etc. Then to start Winpdb, type

winpdb arg0 arg1 ...

Winpdb windows:

There are windows labeled Namespace, Threads, Stack, Source, Console and Command. Note especially those last two, as they give you direct access to the underlying RPDB2 engine. You can directly issue RPDB2 text commands in the Command window, and see messages from RPDB2 in the Console.

Winpdb variable views:

Winpdb source line colors:

Winpdb execution:

Winpdb breakpoint actions:

Winpdb actions upon an exception:

When an exception occurs, you can do the following to learn what happened:

Actions which must be done via the Command window:

Some actions must be done by giving direct text commands to RPDB2 in the Command window, such as:

Further documentation:

Chris Lasher has written a Winpdb tutorial.

Using RPDB2: