Setting up your QGIS IDE

The Eclipse IDE with the PyDev plugin is cross-platform, has advanced debugging tools, and is free.

Note

You can refer to http://pydev.org/manual_101_install.html in order to install PyDev correctly.

This tool makes an excellent PyQGIS IDE. Eclipse allows you to have multiple Python interpreters configured for different Python environments. When you install PyDev, it automatically finds the installed system Python installations. On Windows, you must also add the Python interpreter installed with PyQGIS. On all platforms, you must tell PyDev where the PyQGIS libraries are.

Getting ready

This recipe uses Eclipse and PyDev. You can use the latest version of either package that is supported by your operating system. All platforms besides Windows rely on the system Python interpreter. So, there is an extra step in Windows to add the QGIS Python interpreter.

How to do it…

The following steps will walk you through how to add the QGIS-specific Python interpreter to Eclipse in order to support the running standalone QGIS applications or to debug QGIS plugins.

Adding the QGIS Python interpreter on Windows

The process used to add the QGIS Python interpreter to Eclipse on Windows is different from the process used on Linux. The following steps describe how to set up the interpreter on the Windows version of Eclipse:

1. Open Eclipse.
2. From the Window menu, select Preferences. On OS X, you must click on the Eclipse menu to find the preferences menu.
3. In the pane on the left-hand side of the Preferences window, click on the plus sign next to PyDev.
4. From the list of PyDev preferences, select Interpreter Python.
5. In the pane labelled Python Interpreters, click on the New button.
6. In the Select interpreter dialog, name the interpreter PyQGIS.
7. Browse to the location of the QGIS Python interpreter called python.exe within the bin folder of the QGIS program folder. On OS X and Linux, you use can use the system Python installation. On Windows, Python is included with QGIS. The default location on Windows is C:\Program Files\QGIS Brighton\bin\python.exe, as shown in the following screenshot:
   
8. When you click on the OK button, Eclipse will attempt to automatically add every Python library it finds to the Python path for this interpreter configuration. We need to control which libraries are added to prevent conflicts. Click on the Deselect All button and then click on OK:
   
9. Eclipse will issue a warning dialog because you haven't selected any core libraries. Click on the Proceed anyways button, as shown here:
   

Adding the PyQGIS module paths to the interpreter

Apart from adding the Python interpreter, you must also add the module paths needed by PyQGIS using the following steps. These steps will require you to switch back and forth between QGIS and Eclipse:

1. Start QGIS.
2. Start the QGIS Python Console from the Plugins menu.
3. Use the sys module to locate the PyQGIS Python path, as described in the previous recipe, Setting the environment variables:

   import sys
   sys.path
   

4. We also want to add the PyQGIS API. Next, find that path using the QGIS Python Console by typing the following command:

   qgis

5. For each path in the returned lists, click on the New Folder button in Eclipse's Libraries pane for your QGIS interpreter, and browse to that folder until all the paths have been added. If a given folder does not exist on your system, simply ignore it, as shown here:
   
6. Click on the OK button in the Preferences dialog.

Adding the PyQGIS API to the IDE

To take full advantage of Eclipse's features, including code completion, we will add the QGIS and Qt4 modules to the PyQGIS Eclipse interpreter preferences. The following steps will allow Eclipse to suggest the possible methods and properties of QGIS objects as you type; this feature is known as autocomplete:

1. In the PyDev preferences for the PyQGIS Interpreter, select the Forced Builtins tab, as shown in the following screenshot:
   
2. Click on the New button.
3. In the Builtin to add dialog, type qgis:
   
4. Click on the OK button.

Adding environment variables

You will also need to create a PATH variable, which points to the QGIS binary libraries, DLLs on Windows, and other libraries needed by QGIS at runtime on all platforms.

1. In the PyDev preferences dialog, ensure that the PyQGIS interpreter is selected in the list of interpreters.
2. Select the Environment tab.
3. Click on the New button.

In the Name field, enter PATH.

1. For the Value field, add the path to the QGIS program directory and to any QGIS directories containing binaries separated by a semicolon. The following is an example from a Windows machine:

   C:\Program Files\QGIS Brighton;C:\Program Files\QGIS Brighton\bin;C:\Program Files\QGIS Brighton\apps\qgis\bin;C:\Program Files\QGIS Brighton\apps\Python27\DLLs
   

How it works…

Eclipse and PyDev use only the information you provide to run a script in the Eclipse workspace. This approach is very similar to the popular Python tool virtualenv, which provides a clean environment when writing and debugging code to ensure that you don't waste time troubleshooting issues caused by the environment.