Debugging Python Code on the Raspberry Pi with Wing IDE

May 06, 2015

Wing IDE is an integrated development environment that can be used to develop and debug Python code running on the Raspberry Pi. Wing provides auto-completion, call tips, a powerful debugger, and many other features that help you write, navigate, and understand Python code.


The Raspberry Pi is not really capable of running Wing IDE itself, but you can set up Wing IDE on a computer connected to the Raspberry Pi to work on and debug Python code remotely.

To do this, you will first need (1) a network connection between the Raspberry Pi and the computer where Wing IDE will be running, and (2) a way to share files between the two computers.

The easiest way to connect the Raspberry Pi to your network is with ethernet, or see the instructions at the end of Using Wing IDE with Raspberry Pi for configuring a wifi connection.

For file sharing, use Samba, or simply transfer a copy of your files to the Raspberry Pi using scp or rsync.

Installing and Configuring the Debugger

Once you have a network connection and some sort of file sharing set up, the next step is to install and configure Wing IDE's debugger. This is done as follows:

  • If you do not already have Wing IDE 5.1.5 or later installed, download a free trial on Windows, Linux, or OS X.
  • Download the Raspberry Pi debugger package to your Raspberry Pi and unpack it with tar xzf wing-debugger-raspbian-6.0.1-1.tgz. This creates a directory named wing-debugger-raspbian-6.0.1-1.
  • Launch Wing IDE and make sure that Accept Debug Connections is checked when you click on the bug icon in the lower left of Wing's main window. Hovering the mouse over the bug icon will show additional status information, including the port Wing is listening on, which should be 50005 by default.
  • Copy wingdebugpw from the machine where you have Wing IDE installed to the Raspberry Pi and place it into the directory wing-debugger-raspbian-6.0.1-1. This file is located in the Settings Directory, which is listed 5th in Wing's About box.
  • On the Raspberry Pi, use /sbin/ifconfig to determine the IP address of the Raspberry Pi (not, but instead the number listed under eth0 or wlan0 if you're using wifi).
  • On the host where Wing IDE is running (not the Raspberry Pi), establish an ssh reverse tunnel to the Raspberry Pi so the debugger can connect back to the IDE. On Linux and OS X this is done as follows:

    ssh -N -R 50005:localhost:50005 <user>@<rasp_ip>

    You'll need to replace <user>@<rasp_ip> with the login name on the Raspberry Pi and the ip address from the previous step.

    The -f option can be added just after ssh to cause ssh to run in the background. Without this option, you can use Ctrl-C to terminate the tunnel. With it, you'll need to use ps and kill to manage the process.

    On Windows, use PuTTY to configure an ssh tunnel using the same settings on the Connections > SSH > Tunnels page: Set Source port to 50005, Destination to localhost:50005, and select the Remote radio button, then press the Add button. Once this is done the tunnel will be established whenever PuTTY is connected to the Raspberry Pi.

  • In Wing IDE's Preferences, use the Debugger > External/Remote > Location Map preference to set up a mapping from the location of your files on the remote host (the Raspberry Pi) and the machine where the IDE is running.

    For example, if you have files in /home/pi/ on your Raspberry Pi that match those in /Users/pitest/src/ on the machine where Wing is running, then you would add those two to the location mapping for, with home/pi/ as the remote directory and /Users/pitest/src/ as the local directory.

    Don't add a location map for the Raspberry Pi's ip address because your ssh tunnel makes it look like the connection is coming from and not the Raspberry Pi.

Invoking the Debugger

There are two ways to invoke the debugger: (1) from the command line, or (2) from within your Python code. The latter is useful if debugging code running under a web server or other environment not launched from the command line.

Debugging from the Command Line

To invoke the debugger without modifying any code, use the following command:

wing-debugger-raspbian-6.0.1-1/wingdb arg1 arg2

This is the same thing as python arg1 arg2 but runs your code in Wing's debugger so you can stop at breakpoints and exceptions in the IDE, step through your code, and interact using the Debug Probe in the Tools menu.

By default this runs with python and connects the debugger to localhost:50005, which matches the above ssh tunnel configuration. To change which Python is run, set the environment variable WINGDB_PYTHON:

export WINGDB_PYTHON=/some/other/python

Starting Debug from Python Code

To start debug from within Python code that is already running, edit wing-debugger-raspbian-6.0.1-1/ and change the line WINGHOME = None to WINGHOME = /home/pi/wing-debugger-raspbian-6.0.1-1 where /home/pi should be replaced with the full path where you unpacked the debugger package earlier. Use pwd to obtain the full path if you don't know what it is.

Copy your edited into the same directory as your code and add import wingdbstub to your code. This new line is what initiates debugging and connects back to the IDE through the ssh tunnel.

An alternative to editing is to set WINGHOME in the environment instead with a command like export WINGHOME=/home/pi/wing-debugger-raspbian-6.0.1-1.

Further Reading

For additional configuration options and trouble-shooting, see Using Wing IDE with Raspberry Pi.

Use the Tutorial in Wing's Help menu to learn more about the features available in Wing IDE, or take a look at the Wing IDE Quickstart Guide.

More information on Wing IDE can be found in the product overview.

Share this article:

Debugging Python Code on the Raspberry Pi with Wing IDE