Last Update: 2020-08-12
If you like to develop an EnMAP-Box application, or more general, a QGIS and Qt application, we recommend to use a state-of-the-art Integrated Development Environment (IDE) like PyCharm. It offers run-time debugging, code completion, spell-checking, syntax highlighting, SCM support, unit-testing and many other helpful things.
Furthermore, we recommend to install QGIS within a conda / anaconda environment. The installation is (almost) the same on macOS, windows or linux, it is much easier to install additional python packages and does not require admin rights.
1. Have Git installed¶
If not, download and install Git from https://git-scm.com/downloads
Check if git is installed to your local shell, e.g. as:
C:\Windows\System32>git --version git version 2.26.0.windows.1
2. Clone this repository¶
Clone the EnMAP-Box repository (or a fork) to your local
cd my_repositories git clone https://bitbucket.org/hu-geomatics/enmap-box.git
Now you can use git pull to update your local copy of the EnMAP-Box repository:
cd my_repositories/enmap-box git pull
Replace the repo uri with that of your EnMAP-Box repo fork, if you like to provide code via pull requests.
3. Create a QGIS conda environment¶
- Make sure conda is installed on your system.
- Create a new conda environment named qgis_stable as specified in conda_environment.yml:
conda env create --name qgis_stable --file https://bitbucket.org/hu-geomatics/enmap-box/raw/develop/conda_environment.yml
Depending on the components and applications you like to use, it might be required to install more packages.
If you cloned the EnMAP-Box repository you can also point to the local
--name or the YAML file itself as you wish. For more information on creating and managing conda environments visit the conda documentation
Activate the new environment
conda activate qgis_stable
qgis designer assistant
To easily start applications like PyCharm in this environment, which have not been installed by conda, you might define an alias during the activation of the environment.
Create an activation script and define an alias for PyCharm:
Windows: <your conda installation>/envs/qgis_stable/etc/conda/activate.d/pycharm-activate.bat
@echo off doskey pycharm="<path to pycharm executable>"
MacOS: <your conda installation>/envs/qgis_stable/etc.conda/activate.d/pycharm-activate.sh
alias pycharm='open -a PyCharm\ CE.app'
For completeness, also create a deactivation script:
Windows: <your conda installation>/envs/qgis_stable/etc/conda/deactivate.d/others-deactivate.bat
@echo off doskey pycharm=
MacOS/Linux: <your conda installation>/envs/qgis_stable/etc.conda/deactivate.d/pycharm-deactivate.sh
4. Setup PyCharm¶
Start PyCharm and add my_repositories/enmap-box as new project via File > Open File or Project
If this is not already the case, tell PyCharm where to find your Git-executable. Open File > Settings > Version Control > Git to set Path to Git executable. Press Test to check the used Git version.
whereto return the path of a git-executable that is available in your DOS/Linux/macOS shell
(qgis_stable) C:\>where git C:\Users\geo_beja\AppData\Local\Programs\Git\cmd\git.exe
Switch to Project: enmap-box > Project Interpreter and add your conda qgis_stable python as project interpreter
Switch to Project Structure and add
<your conda installation>/envs/qgis_stable/Library/pythonas additional project content root.
<your conda installation>/envs/qgis_stable/share/qgis/python
<your conda installation>/envs/qgis_stable/QGIS.app/Contents/MacOS/../Resources/python
Right-click on the
pluginssubfolder and select Sources. Now the PyQGIS API is available to your Python installation.
The same way allows you to include other directories to your project’s PYTHONPATH, e.g. to make code available from other folder or repositories.
PyCharm and PyQGIS need the environmental variable
QGIS_PREFIX_PATH, which typically is:
Typical paths are:
OS QGIS_PREFIX_PATH Windows <your conda installation>\envs\qgis_stable\Library Linux <your conda installation>/envs/qgis_stable macOS <your conda installation>/envs/qgis_stable/QGIS.app/Contents/Resources
If not already set in the environment from which you started PyCharm, you can set it explicitly. Open Run > Debug … > Edit Configurations and add the QGIS_PREFIX_PATH to the User environmental variables. This way PyCharm runs python files in a environment with QGIS_PREFIX_PATH defined.
Also define the Environment variables for the Python console. Go to File > Settings > Build, Execution, Deployment > Console > Python Console and add QGIS_PREFIX_PATH to the Environment variables.
You might also like to use the conda environment shell in your Pycharm terminal. Open Tools > Terminal and set the shell path to
cmd.exe "/K" <your conda installation>\Scripts\activate.bat qgis_stable
Test the Python environment
To check if the QGIS API is available, open a Python Console and import the QgsApplication object.
from qgis.core import QgsApplication QgsApplication.instance() is None
The output should return
True, as we have not initialized any QgsApplication.
Now check if we can use the EnMAP-Box API to start the EnMAP-Box
import enmapbox enmapbox.run()
This should initialize a new QgsApplication and start the EnMAP-Box. The outputs printed to the python shell should look like:
Application state: QGIS_PREFIX_PATH env var: D:\miniconda3\envs\qgis_stable\Library Prefix: D:\miniconda3\envs\qgis_stable\Library Plugin Path: D:\miniconda3\envs\qgis_stable\Library/plugins Package Data Path: D:\miniconda3\envs\qgis_stable\Library/. Active Theme Name: Active Theme Path: D:\miniconda3\envs\qgis_stable\Library/./resources/themes\\icons/ Default Theme Path: :/images/themes/default/ SVG Search Paths: D:\miniconda3\envs\qgis_stable\Library/./svg/ C:\Users\geo_beja\AppData\Local\Temp\QGIS-PythonTestConfigPathp1k7w_s_\profiles\default/svg/ User DB Path: D:\miniconda3\envs\qgis_stable\Library/./resources/qgis.db Auth DB Path: C:\Users\geo_beja\AppData\Local\Temp\QGIS-PythonTestConfigPathp1k7w_s_\profiles\default/qgis-auth.db
If the terminal environment was setup well, you can start the EnMAP-Box from the Terminal window as well by
(qgis_stable) ..\enmap-box>python enmapbox
The Qt company provides several tools to that help to create Qt applications and are useful for PyQt and PyQGIS users as well.
The Qt Assistant allows you to browse fast and offline through Qt help files (
*.qch). These files exists for
all Qt classes and the QGIS API. They can be generated event with Sphinx, which allows you to provide your
own source-code documentation as
.qch file as well.
Start the Qt Assistant, e.g. from your PyCharm terminal:
*.qch*files which contain:
Go to Preferences > Add and add the follwing
File Documentation qgis.qch qgis.core, qgis.gui qtcore.qch Qt5.QtCore qtgui.qch Qt5.QtGui qtwidgets.qch Qt5.QtWidgets
Now you can explore the Qt (
Q...) and QGIS (
The Qt Designer is a powerful tool to create GUI frontends by drawing, drag and drop.
Created GUI form files are saved in a XML file ending with
*.ui. These can be called from
python to automatically create the entire GUI backend, e.g. windows and buttons defined with the Qt Designer.
You can start the Qt Designer from your PyCharm terminal by:
Qt Creator is the one-in-all IDE to develop Qt C++ applications. It includes the functionality covered by Qt Assistant (here called Help) and Qt Designer (here called form designer) and helps to browse C++ code. It is the preferred tool to explore the QGIS C++ source code, for example if you like to better understand what it does behind the QGIS python API.
Qt and the Qt Creator are available at https://www.qt.io/download. Ensure to install the code documentation for the same Qt version used by QGIS.
OSGeo4W for Devs¶
If you work on windows and want to test your code based on nightly builds of the upcoming QGIS version, or like to inspect/debug the QGIS C++ API at runtime, you might use the OSGeo4W installer to setup your development environment:
Download the (new) OSGeo4W installer (osgeo4w-setup.exe from https://www.qgis.org/en/site/forusers/download.html )
Install the nightly build branch qgis-dev and related debug symbols qgis-dev-pdb.
Install other required packages, e.g. pip3 etc. Later on. In case of missing packages, search and install via OSGeo4W installer first. If not available there, use the OSGeo4W shell and call pip.
Create a qgis-dev-env.bat to setup your QGIS environment
set OSGEO4W_ROOT=D:\OSGeo4W set QGISDISTR=qgis-dev set DIR_GIT=C:\Program Files\Git\cmd set DIR_LFS=C:\Program Files\Git LFS :: add GIT and LFS to path call "%OSGEO4W_ROOT%\bin\o4w_env.bat" path %OSGEO4W_ROOT%\apps\%QGISDISTR%\bin;%DIR_GIT%;%DIR_LFS%;%PATH% set QGIS_PREFIX_PATH=%OSGEO4W_ROOT:\=/%/apps/%QGISDISTR% set GDAL_FILENAME_IS_UTF8=YES rem Set VSI cache to be used as buffer, see #6448 set VSI_CACHE=TRUE set VSI_CACHE_SIZE=1000000 set QT_PLUGIN_PATH=%OSGEO4W_ROOT%\apps\%QGISDISTR%\qtplugins;%OSGEO4W_ROOT%\apps\qt5\plugins set PYTHONPATH=%OSGEO4W_ROOT%\apps\%QGISDISTR%\python;%OSGEO4W_ROOT%\apps\%QGISDISTR%\python\plugins;%PYTHONPATH%
Don’t forget to make git and git-lfs available in this environment.
Create a qgis-dev-pycharm.bat in the same folder as qgis-dev.bat that starts PyCharm
call "%~dp0\QGIS-dev.bat" set PYCHARM_EXE="C:\Program Files (x86)\JetBrains\PyCharm 2020.3.4\bin\pycharm64.exe" start "PYCHARM" /B %PYCHARM_EXE% :: uncomment to start QGIS :: start "QGIS" /B "%OSGEO4W_ROOT%\bin%QGISDISTR%-bin.exe" %*
Call qgis-dev-pycharm.bat to start PyCharm and set your project settings to:
Project Interpreter: <OSGEO4W>binpython.exe
Terminal Shell Path: cmd.exe “/K” <your path to>qgis-dev.bat (this is why we created two batch files. qgis-dev.bat setups the environment, but does not start any app)
add <OSGEO4W>appsqgis-devpython and <OSGEO4W>appsqgis-devpythonplugins as source folders
- Clone the QGIS repo and checkout the latest master
- Install Visual Studio and open the QGIS repo
- Start a QGIS desktop, e.g. with qgis-dev from the OSGeo4W shell
- Attach the Visual Studio debugger to a QGIS desktop instance
- Open Debug > Attach to Process (CTRL+ALT+P)
- Filter available processes by ‘QGIS’ and, e.g., select qgis-dev-bin.exe
- Press the Attach button