Related Plugins and Tags

QGIS Planet

Remote debugging QGIS plugins using PyCharm

Wow it’s been a long time since I posted anything here….but I’m back with another (hopefully) useful howto. Over the last six months or so I have made a rather dramatic shift away from using VIM as my primary development environment for everything to using IDE’s for my python development work. I spent the first... Read more »

Remote debugging QGIS plugins using PyCharm

Wow it's been a long time since I posted anything here....but I'm back with another (hopefully) useful howto. Over the last six months or so I have made a rather dramatic shift away from using VIM as my primary development environment for everything to using IDE's for my python development work. I spent the first 4 or so of those months using Eclipse PyDev which is excellent but has certain issues, particularly from a QGIS context. Most of the issues relate to my not being able to get it to reliably recognise the QGIS API after adding the QGIS python directories to the package search path and the lack of decent refactoring tools. In my java programming days of yore, I used to love the refactoring tools that Eclipse provided, but unfortunately these are not carried through to PyDev.

Lately I have been using PyCharm which is a dedicated python IDE also written in Java (ironic). I'm not going to attempt to review all of PyCharm here (Guido van Rossum already did that but bear in mind the review is two years old and the software has surely advanced a lot since then). I will say there are two things that I find not as pleasant to use in PyCharm (compared to PyDev) - its PyLint and PEP8 checkers. In the projects I work on we follow PEP8 very strictly and not having a proper integrated tool for this is a real PITA. There are work arounds however so it is not a lost cause, but it would be nice if the developers took this a little more seriously:

On the other hand, I simply do not see the value of highlighting PEP 8 violations in the editor, especially in the middle of code modifications. We'd rather spend our time implementing inspections that report actual problems with the code, and not formatting nit-picks. - Dmitry Jemerov

One other big downside to PyCharm is that it is not open source software which goes against the grain somewhat. They do however provide free licensing to those using it for bona fide open source development work, so don't let the price tag deter you if you are planning to use if for a FOSS project.

Read on to see how I use PyCharm for QGIS development...

PyCharm for QGIS remote debugging

Why use PyCharm? Well it happens to be a really nice platform for QGIS python / python plugin development. For this article I am going to focus on the steps needed to remote debug python scripts / plugins running inside QGIS. The process is conceptually the same as remote debugging using Eclipse/PyDev - which I have blogged about previously. I am going to start with the assumption that you have your PyCharm set up and your plugin basics in place and now you are at the point where you wish to debug your software while it is running in QGIS. Let me prefix this by saying that I very seldom need to use this technique since our code is heavily tested (by means of a python test suite) so in most cases I can just debug a particular test directly without needing to remotely attach to a python process in QGIS. So the first thing you need to do is set up a python debug server (provided as part of PyCharm). To do this,  choose edit configurations from the task list:

Create a new run configuration

Next click on the little '+' icon and choose python remote debug:


Set the following options:

  • Local host name: localhost
  • Port: 53100

Note that you can use any high port that you like (assuming it is unused).

You will notice that on the dialog it gives you some handy hints as to what needs to be inserted into your code in order to enable the trace point.

Creating the debug server run configuration

The next thing you need to do is add a couple of lines to the module that you wish to debug (this is also described in the above dialog). First, in your imports add this:

from pydev import pydevd

And then in the place where you wish execution to halt, add this line:


You can also try using 'localhost' instead of your IP address.

The last thing you need to have in place before you can test is pydevd needs to be in your PYTHONPATH in the context of the running plugin. In my case I simply extracted the pydevd egg supplied in the root of the PyCharm installation into my plugin directory:

cp ~/apps/pycharm-2.5.2/pycharm-debug.egg .
unzip pycharm-debug.egg

There are a number of other ways you could do this, for example by changing your code to add the pydev directory into sys.path.

Ok now you are all set. One thing to remember is that the settrace line is just the initial breakpoint - you can set additional breakpoints in your code using normal PyCharm debugging techniques. Now launch your PyCharm debug server configuration by clicking the little run icon next to it (highlighted in red below):

Start the debug server

After this you will see some output like this in the PyCharm run panel:

Starting debug server at port 53100
Waiting for connection...

Next fire up your copy of QGIS and open the plugin that will trigger your settrace. When the trace point is hit, PyCharm will enter debug mode and highlight the trace line in blue like this:

PyCharm debugging a remote process

Now you can step through your code, inspect variables and generally have a productive time understanding your code. I'll hopefully post a follow up article on how to set up PyCharm for QGIS development in the future! Happy hacking!

Back to Top

Sustaining Members