Getting started with Python and QGIS can be a bit overwhelming. In this post we
give you a quick start to get you up and running and maybe make
your PyQGIS life a little easier.
There are likely many ways to setup a working PyQGIS development
environment—this one works pretty well.
Contents
Requirements
- OSGeo4W Advanced Install of QGIS
- pip (for installing/managing Python packages)
- pb_tool (cross-platform tool for compiling/deploying/distributing QGIS plugin)
- A customized startup script to set the environment (pyqgis.cmd)
- IDE (optional)
- Vim (just kidding)
We’ll start with the installs.
Installing
Almost everything we need can be installed using the OSGeo4W installer available on the
QGIS website.
OSGeo4W
From the QGIS website, download the appropriate network installer (32 or 64 bit)
- Run the installer and choose the Advanced Install option
- Install from Internet
- Choose a directory for the install—I prefer a path without spaces such as
C:\OSGeo4W
- Accept default for local package directory and Start menu name
- Tweak network connection option if needed on the Select Your Internet
Connection screen
- Accept default download site location
- From the Select packages screen, select the following for installation:
Desktop -> qgis: QGIS Desktop
Libs -> qt4-devel
(needed for lrelease/translations)
Libs -> setuptools
(needed for installing pip)
When you click Next a bunch of additional packages will be suggested—just
accept them and continue the install.
Once complete you will have a functioning QGIS install along with the other
parts we need. If you want to work with the nightly build of QGIS, choose
Desktop -> qgis-dev
instead.
If you’ve already installed QGIS using the OSGeo4W installer, just install the
qt4-devel
and setutools
packages. If you installed QGIS using the
standalone installer, the easiest option is to remove it and install
from OSGeo4W. You can run both the standalone and OSGeo4W versions on the same
machine, but you need to be extra careful not to mix up the environment.
Setting the Environment
To continue with the setup, we need to set the environment by creating a .cmd
script. The following is adapted from several sources, and trimmed down to the
minimum. Copy and paste it into a
file named pyqgis.cmd
and save it to a convenient location (like your HOME
directory).
@echo off
SET OSGEO4W_ROOT=C:\OSGeo4W
call "%OSGEO4W_ROOT%"\bin\o4w_env.bat
call "%OSGEO4W_ROOT%"\apps\grass\grass-6.4.3\etc\env.bat
@echo off
path %PATH%;%OSGEO4W_ROOT%\apps\qgis\bin
path %PATH%;%OSGEO4W_ROOT%\apps\grass\grass-6.4.3\lib
set PYTHONPATH=%PYTHONPATH%;%OSGEO4W_ROOT%\apps\qgis\python;
set PYTHONPATH=%PYTHONPATH%;%OSGEO4W_ROOT%\apps\Python27\Lib\site-packages
set QGIS_PREFIX_PATH=%OSGEO4W_ROOT%\apps\qgis
set PATH=C:\Program Files (x86)\Git\cmd;C:\Program Files (x86)\Vim\vim74;%PATH%
cd %HOMEPATH%\development
cmd.exe
You should customize the set PATH
statement to add any paths you want
available when working from the command line. I added paths to my git
and
vim
installs.
The cd %HOMEPATH%\development
statement starts the shell in my normal working
directory—customize or remove as you see fit.
The last line starts a cmd
shell with the settings specified above it. We’ll
see an example of starting an IDE in a bit.
You can test to make sure all is well by double-clicking on our pyqgis.cmd
script, then starting Python and attempting to import one of the QGIS modules:
C:\Users\gsherman\development>python
Python 2.7.5 (default, May 15 2013, 22:44:16) [MSC v.1500 64 bit (AMD64)] on win
32
Type "help", "copyright", "credits" or "license" for more information.
>>> import qgis.core
>>>
If you don’t get any complaints on import, things are looking good.
Python Packages
We need a couple of Python packages as well.
pip
There are several ways to install pip
, but since we installed setuptools
we
can use easy_install
:
easy_install pip
Make sure to issue this command from your customized shell (double-click on
pyqgis.cmd to start it).
pb_tool
With pip
installed we can use it to install pb_tool
:
pip install pb_tool
More information on using pb_tool
is available on the
project website.
Working on the Command Line
Just double-click on your pyqgis.cmd
script from the Explorer or a desktop
shortcut to start a cmd shell. From here you can use Python interactively and
also use pb_tool
to compile and deploy your plugin for testing.
IDE Example
With slight modification, we can start our IDE with the proper settings
to recognize the QGIS libraries:
@echo off
SET OSGEO4W_ROOT=C:\OSGeo4W
call "%OSGEO4W_ROOT%"\bin\o4w_env.bat
call "%OSGEO4W_ROOT%"\apps\grass\grass-6.4.3\etc\env.bat
@echo off
path %PATH%;%OSGEO4W_ROOT%\apps\qgis\bin
path %PATH%;%OSGEO4W_ROOT%\apps\grass\grass-6.4.3\lib
set PYTHONPATH=%PYTHONPATH%;%OSGEO4W_ROOT%\apps\qgis\python;
set PYTHONPATH=%PYTHONPATH%;%OSGEO4W_ROOT%\apps\Python27\Lib\site-packages
set QGIS_PREFIX_PATH=%OSGEO4W_ROOT%\apps\qgis
set PATH=C:\Program Files (x86)\Git\cmd;C:\Program Files (x86)\Vim\vim74;%PATH%
cd %HOMEPATH%\development
start "PyCharm aware of Quantum GIS" /B "C:\Program Files (x86)\JetBrains\PyCharm 3.4.1\bin\pycharm.exe" %*
We only changed the last line, adding the start
statement with the path to the
IDE (PyCharm). If you save this to something like pycharm.cmd
, you can
double-click on it to start PyCharm. The same method works for other IDEs, such
as PyDev.
Within your IDE settings, point it to use the Python interpreter included with
OSGeo4W—typically at: %OSGEO4W_ROOT%\bin\python.exe
. This will make it pick up
all the QGIS goodies needed for development, completion, and debugging. In my
case OSGEO4W_ROOT
is C:\OSGeo4W
, so in the IDE, the path to the correct
Python interpreter would be: C:\OSGeo4W\bin\python.exe
.
Make sure you adjust the paths in your .cmd scripts to match your
system and software locations.
Workflow
Here is an example of a workflow you can use once you’re setup for development.
Creating a New Plugin
- Use the Plugin Builder plugin to create a starting point [1]
- Start your pyqgis.cmd shell
- Use
pb_tool
to compile and deploy the plugin (pb_tool deploy
will do it all in one pass)
- Activate it in QGIS and test it out
- Add code, deploy, test, repeat
Working with Existing Plugin Code
The steps are basically the same was creating a new plugin, except we start by
using pb_tool
to create a new config file:
- Start your pyqgis.cmd shell
- Change to the directory containing your plugin code
- Use
pb_tool create
to create a config file
- Edit
pb_tool.cfg
to adjust/add things create
may have missed
- Start at step 3 in Creating a New Plugin and press on
Troubleshooting
Assuming you have things properly installed, trouble usually stems from an incorrect environment.
- Make sure QGIS runs and the Python console is available and working
- Check all the paths in your
pygis.cmd
or your custom IDE cmd script
- Make sure your IDE is using the Python interpreter that comes with OSGeo4W
[1] Plugin Builder 2.6 will support generation of a pb_tool config file