Using Eclipse to remote debug Python on a Raspberry Pi


Using Eclipse on a workstation to debug Python scripts running on a Raspberry Pi is a very powerful python debugging tool. In this howto post the remote debugging workstation will be Linux, my favorite OS, but this should also work the same if you are using a Windows OS remote workstation. You will need to install Eclipse IDE and Pydev plugin on the workstation. On the Raspberry Pi you can install the Eclipse IDE and Pydev plugin, but running Eclipse on the Pi is painfully show, so I don’t recommend installing Eclipse IDE on the Pi we will only be installing only the Pydev plugin on the Pi to makes this work.

You might be asking yourself why not install with the package manger….first reason is current apt version is Eclipse Mars 3.8 and we will be installing the latest stable version (at the time on this writing) Eclipse Neon 4.6 or higher. Second reason is Eclipse is very picky about what versions on both Eclipse itself and the plugin’s and I have found it to be much more crash proof if you install the way I’m describing in this how-to. For example you will not be able to use the install wizard or drag and drop to install PyDev (plugin that allows Python debugging) because it needs the 4.x Neon.

Network Connection

Both devices need to communicate over an IP connection this can be a local network LAN or even over the Internet WAN. For this post I’m assuming the Pi and the workstation are on the same LAN network. Over the Internet you need to make sure any firewalls between the two device will pass port 5678. You will also need to setup port forwarding to the remote workstation. The Pi makes a connection to the workstation when the Python script Pydev debug function pydevd.settrace() is called, more on that later on.

Eclipse Remote Debug

Click to enlarge


Check the Java JRE Release number

Eclipse IDE is a java application and the latest as of this post is Eclipse Platform 4.6 Neon. It requires Java 8 (or later) JRE or JDK to run. The installer also uses java, so the first thing you need to do is check and see if you have Java Runtime Environment JRE installed and correct release.

$ java -version
java version “1.8.0_112”
Java(TM) SE Runtime Environment (build 1.8.0_112-b15)
Java HotSpot(TM) 64-Bit Server VM (build 25.112-b15, mixed mode)

On my Linux workstation it shows java version “1.8.0_112” which is Java 8 you look at the second digit of the version to determine the release number, so 1.7 would be Java 7 release. If you don’t have Java release 8 or higher or you get “command not found” you need to figure out why and fix before continuing.

Installing the Eclipse IDE and Pydev plugin on the Remote Workstation

How that you have verified you have Java 8 JRE or higher installed lets download the Eclipse installer. Open your browser and point it to and download the installer. Once you select you system type it will download a tar.gz file “eclipse-inst-linux64.tar.gz” after it downloads unpack it.

$ tar xvfz eclipse-inst-linux64.tar.gz

Change into the “eclipse-installer” sub directory you just unpacked the install to and run the installer.

$ cd eclipse-installer
$ ./eclipse-inst



Click to Enlarge

The Installer will load and you can pick any of the IDE’s that best fits your needs, I chose “Eclipse IDE for PHP Developers”, since I also program in php and includes GIT plugin. After you select one it will then ask you where you want to install to, the default is home directory. Remember or write down where it is install you will need that later to run eclipse.

Click to Enlarge

Click to Enlarge

After it installs chose launch and eclipse should load. To run eclipse later you will find it in the /home/your_user_name/eclipse/php-neon/eclipse for my install /home/billf/eclipse/php-neon/eclipse. To run eclipse from the command line:

$ cd /home/billf/eclipse/php-neon/eclipse
$ ./eclipse


Click to Enlarge

Click to Enlarge


Installing the Pydev plugin

You need the Pydev plugin to debug and create Python code in Eclipse. There are several ways to install the plugin, but the easiest and fastest is to go to the site and use the drag and drop feature. To do that you need to have eclipse up and go to  Second option to install a plugins is from within Eclipse Help -> Eclipse Maketplace. Once at the Eclise Marketplace search for Pydev.


Click to Enlarge

Click to Enlarge

You can use the Drag and Drop install plugin by dragging the Install button button to your running Eclipse workspace. You may need to minimize the welcome window so the workspace is available should look like this:

Click to Enlarge

Click to Enlarge

Once you drag and drop the install button this window will appear:

Click to Enlarge

Click to Enlarge

Make sure all the boxes are check then hit confirm. It will start the install and stop popping up this window

Click to Enlarge

Click to Enlarge


You need to hit “Select All” and then “OK” if you do not hit “Select All” it will terminate the install with no message and you have to reinstall the plugin. It will continue to install the plugin and ask you to restart once it finishes. Select restart and Eclipse will restart and you will have the Pydev plugin installed.

There is one other plugin I recommend using that allows to to ssh into the Pi and browse the file and use Eclipse IDE features to develop and edit existing Python scripts. The install is the same as installing Pydev. The plugin is called “Remote System Explorer” search for in the market place and install.

Click to Enlarge

Click to Enlarge


Once you have completed the Eclpise install and plugin installs you will have a IDE that can debug and develop Python code.

Configuring the Raspberry Pi to allow remote debugging

Like I mentioned in the overview you can install Eclipse on the Pi, but it is painfully slow, so I do not recommend. If you want to install and try for yourself just “sudo apt-get install eclipse”,  or follow the the same steps you did to install Eclipse and the Pydev plugin from above for the remote workstation and you can do both the remote debugging I describe here and standalone. You can skip the rest of the Pi setup below and go right to testing if you installed Eclipse and PyDev plugin on the Pi.

A better option is to only install the PyDev core files on the Pi. I found out you can preform remote debugging on the Raspberry Pi by just installing the pysrc files from the PyDev plugin for Eclipse. What this does is allow to you preform remote debugging without installing Eclipse on the Raspberry Pi, so this complete setup can be done via ssh on a headless Pi.  The other plus for only installing what you need is the full Eclipse install is over 200M where just the PyDev pysrc is only about 20M.

Installing PyDev minimum on the Pi

The location for the PyDev source plugin files is when you go there you will see it is just a redirect to the latest stable source.

Click to Enlarge

Click to Enlarge

Click on the link and it will take you to the latest stable version then select plugins.

Click to Enlarge

Click to Enlarge

In the plugin source sub-directory find org.python.pydev.core_6.5.0.201809011628.jar  depending on the release the numbers will change.

Click to Enlarge

Click to Enlarge

Don’t download by clicking on the link we will use wget to download directly on the Pi. The source pysrc we are installing here and the version of the plugin on the workstation do not need to match, so once you install this on the Pi and a new version of PyDev is updated on the remote workstation you don’t need to go back and update the version we are installing on the Pi. Having said that, updating this on the Pi from time to time is a good idea since there may be fixes that would improve performance or security.

How to install on the Pi

To install the necessary files, ssh into the Pi and create a directory in your home directory that we will install the pysrc into. I doesn’t matter where you create it, but you need note where you are installing pysrc it is used in the “sys.path.append()” function in your Python script you will be debugging. Create the directory and change into that directory:

$ mkdir $HOME/eclipse-PyDev
$ cd $HOME/eclipse-PyDev/


Next step is to download the source code. To do this right click on the link and select “Copy link location” then type “wget” and paste the source URL.
Note:you need to remove the colon they put in front of org in the link name or else you will get a 404: not found from wget.

$ ~/eclipse-PyDev $ wget

Next step we need to unpack using unzip.

$ ~/eclipse-PyDev $ unzip org.python.pydev.core_6.5.0.201809011628.jar

If you followed the above step you have a remote workstation that can debug Python scripts using Eclipse IDE.

Optional: You will get a warning on the Pi when you enable remote debugging and you run the script, you need to do the following to fix. Install cython and build command to get rid of this warning message. Doesn’t seem to affect the debugging, so you can skip, but is easy to fix.

warning: Debugger speedups using cython not found. Run ‘”/usr/bin/python” “/home/billf/eclipse-PyDev/pysrc/” build_ext –inplace’ to build.

Install both cython and cython3 so we can support both 2.x and 3.x Python scrips.

sudo apt-get install cython cython3

Next build the ext’s for for both Python 2.x and Python 3.x

/usr/bin/python /home/billf/eclipse-PyDev/pysrc/ build_ext –inplace
/usr/bin/python3 /home/billf/eclipse-PyDev/pysrc/ build_ext –inplace

The above steps will get rid of the warning on the Pi when you run a script in remote debug mode.

End Optional:

Testing Eclipse remote debug Python on a Raspberry Pi


Here is a example of a simple test script with a RemoteDebug() function you can add and call in any Python scripts you write to do remote debugging works for both Python 2.x and Python 3.x scripts

import sys
import os

# pydev remote debugger function 
def RemoteDebug():


			import pydevd
			global pydevd

			# if you want debug to break as soon as the pydevd.sttrace 
			# function below is called set "suspend=True and the debug will start on the next line of 
			# python code after the function call.
			# if you want to go directly to a break point change "supend=False" and 
			# insert "pydevd.settrace()"function where you want the break point.
			# pydevd.settrace('Remote IP address or hostname',port=5678, suspend=True)
			pydevd.settrace('mars', port=5678, suspend=True)
			# stdoutToServer and stderrToServer redirect stdout and stderr to eclipse console
			# pydevd.settrace('', stdoutToServer=True, stderrToServer=True)

	#   settrace() debug arguments .
	#   host: the user may specify another host,if the debug server is not in the 
	#	  same machine (default is the localhost)
	#   stdoutToServer: when this is true, the stdout is passed to the debug server
	#   stderrToServer: when this is true, the stderr is passed to the debug server
	#	            so that they are printed in its console and not in this process console.
	#   port: specifies which port to use for communicating with the server
	#	  default port 5678
	#   suspend: whether a breakpoint should be emulated as soon as this function is called.
	#   trace_only_current_thread: determines if only the current thread will be traced or 
	#			       all current and future threads will also have the tracing enabled.
	#   overwrite_prev_trace: if True we'll reset the frame.f_trace of frames which are already 
	#	                  being traced
	#   patch_multiprocessing: if True we'll patch the functions which create new processes 
	#	                   so that launched processes are debugged.

			 # hack force 'xterm' terminal for pydevd debugging. Else will get terminal error with curses module			 
			os.environ['TERM'] = 'xterm'
			print ("Remote Debug works")

		except ImportError:
			sys.stderr.write("Error: " + 
			   "You must add pysrc path to the above sys.path.append statement or to your PYTHONPATH.\n")

def main():

		global remote_debug

		remote_debug = True

		# Check to see if we enabled remote debugging
		if remote_debug == True:

		print ("Goodbye")  

if __name__ == "__main__":

Using Eclipse is out of the scope of this how-to there are many youtube video’s, but will get you started if you never used it before…..

Couple of things you need to understand are prospectives and debugging basics. Lets first talk about prospectives in Eclipse. A prospective is a view of the workspace and depending on what you are doing the windows in that prospective change. For example when in the debug prospective windows that pertain to debugging will display window for Variables, Debug server, the Python script you will be stepping through and the icons below the menu will change too. You can move the windows around change the size of them delete them, minimize, maximize them. Try playing around with them…the good news is it is very easy to reset them back to the default. In the top menu:

To reset the current prospective back to its default:
Windows -> Prospective – > Reset Prospective


To go to a prospective you can use the icons in the upper right next to a box that says “Quick Access” no icons will display there until you go to a prospective at least once. If you know the name of the prospective you can type in in the “Quick Access” box for example “debug” will pop-up as a Prospective. We will need to go to the Prospective “debug” to test our remote debugging, so type debug in the “Quick Access” box and select Prospective – Debug.

Click to Enlarge

Click to Enlarge

To try your first remote debug you need to have the example script from above installed on the Pi. For this test installing it in the home directory is fine. From the workstation you are running Eclipse on open up a shell and ssh into the Pi. Copy and paste the example into a file called “”. edit line 21 and put in the IP address of the workstation running Eclipse, not the Pi’s IP address.

Edit line 21 of the change to the IP of the pc running Eclipse debug server, not the PI’s IP:
pydevd.settrace(‘‘, port=5678, suspend=True)

In Eclipse go to the upper menu and start the Debug Server:

To start the remote Debug server in Eclipse:
PyDev -> Start Debug Server

You will see in the console window “Debug Server at port: 5678.

Now go to the ssh shell session and run the the example.


You should see the Eclipse debug server connect it should look like this.

Click to Enlarge

Click to Enlarge

Use the icons below the menu to step through the lines of code.

Once you step through the code the debug will terminate. Back on the ssh session for the Pi you will see output from the print statement display.


$ python
Remote Debug works


Happy Debugging!!!


4 Responses to Using Eclipse to remote debug Python on a Raspberry Pi

  1. Javier Andrés Loaiza Monsalve says:

    Hello Friend

    When i try this with python3 it shows:

    ImportError: No module named ‘pydevd’

    • Bill Fahrnekrug says:

      @Javier, please make sure you change the path on the host you are trying to debug (from the test script above) to path on your system.
      For example on my system:

      To find the directory on the remote host you are trying to debug.

      On remote host issue the command “find”:
      $find / -name 2>/dev/null

      Result on my system:

      If you don’t find then on your system you haven’t installed pydevd per the instructions above.

  2. Thank you so much for your careful directions. I just followed them with Eclipse 2020-06, and they worked on the first try.

    One possible addition: in order for imports of sister scripts to work, they need to be opened once within Eclipse. This action creates a kind of surrogate for the file in the local machine. Once opened, it is fine to close them right away. The same applies to files like foo.sqlite. Your remote script won’t see it until you double clicked on it once in the RSE pane. The file will open in whatever application is associated with the extension. Again, can be closed again right away. Maybe there is an easier way to get a whole folder touched at once.

    One other small point: when entering the debug perspective, the explorer pane reverts back to the local package explorer. To see the remote files again, re-enter the RSE perspective; most conveniently by clicking its icon in the upper right of the Eclipse window.

    • Bill Fahrnekrug says:

      Thanks, Andreas for the comment!

      As you know Eclipse is well documented and there are many ways to set-up the workspace and debug with it. You have some great tips to use RSE, the “pi” could be any place that has a way to connect via IP, could be a lab enviroment (private) or IOT (public).


Leave a Reply to Bill Fahrnekrug Cancel reply

Your email address will not be published. Required fields are marked *