Leveraging Osgeo4W And Conda Environments To Simplify Pyqgis Development On Windows

The Hassle of Setting Up PyQGIS on Windows

Issues with conflicting Python installations

A common challenge faced when configuring Python for QGIS development on Windows is managing conflicting Python installations. Many Windows environments have multiple Python versions preinstalled or manually installed for various applications. Determining which Python installation is associated with QGIS and its plugins can be confusing. Often plugins fail to load properly due to referencing the wrong Python version or not having access to the correct site-packages directories.

Challenges with dependency management

Properly installing Python dependencies for PyQGIS development by hand can be an exercise in frustration. Libraries like NumPy and GeoPandas have compiler requirements that must be set up on Windows systems. Tracking down issues caused by missing DLLs or unmet environmental variables often requires significant troubleshooting time. Even when dependencies are manually installed, maintaining the correct versions across projects is challenging.

Difficulties ensuring QGIS API compatibility

On top of Python dependency problems, the QGIS Python API itself relies on very specific software versions. The API calls, documentation, plugin signatures, and processing framework for QGIS are tightly coupled with targeted releases. If development environments leverage the wrong QGIS installation, plugins can fail unexpectedly. Keeping the Python environment and QGIS release in sync by hand is time-consuming and prone to issues.

Introducing OSGeo4W and Conda – A Powerful Combo

Overview of OSGeo4W capabilities

OSGeo4W provides Windows users with an automated installer for open source GIS software including QGIS. It handles downloading packages, resolving software dependencies, and configuring environmental paths. The power of OSGeo4W is its simplification of the complex QGIS compilation process. Multiple versions of QGIS can be installed side by side with independent Python environments via the OSGeo4W setup.

Conda’s virtual environment strengths

Conda brings best-in-class Python virtual environment management to Windows. Prebuilt binary packages remove any dependency compilation requirements. Conda environments fully isolate project libraries and Python installations. That enables smooth side-by-side deployments of multiple interpreters, site-packages repositories, and QGIS plugin sets. Environments can also be exported and copied for distribution across systems.

How they complement each other

Together OSGeo4W and Conda provide turnkey access to tailored, reproducible QGIS developer environments on Windows. OSGeo4W supplies the backbone QGIS build while Conda environments handle Python package management. Each component focuses on simplifying historically error-prone processes. The combined workflow relieves the headaches of configuring QGIS and coordinating compatible plugins.

Creating an Optimized PyQGIS Environment

Step-by-step guide to install and configure

This section walks through building a streamlined OSGeo4W and Conda stack for PyQGIS work. First install the latest OSGeo4W release, taking care to allow environmental path changes. Choose the QGIS long term release and Python 3.x combination best suited for your plugins. After OSGeo4W is configured, build a Conda environment to match via:

conda create --name my_qgis_env python=3.9

This will replicate the major version found in OSGeo4W. Next install PyQGIS and its prerequisites like so:

conda install -c conda-forge numpy gdal scipy matplotlib pyqgis

Activating the Conda environment

With the environment built, enable it via the following command. Note that this must be re-run per new terminal session:

conda activate my_qgis_env

Verifying QGIS and Python versions

Check that the activated Conda Python environment matches expectations by:

python --version

Additionall confirm QGIS references the correct interpreter:

qgis --version

With aligned Python and QGIS releases via OSGeo4W and Conda, the foundation is ready for PyQGIS development.

Loading PyQGIS in a Jupyter Notebook

Example code to import Processing and iface

One benefit of combining OSGeo4W and Conda is using PyQGIS code directly in Jupyter notebooks. Ensure your notebook kernel matches the Conda environment version, then import PyQGIS libraries:


import processing
from qgis.core import *
import qgis.utils

iface = qgis.utils.iface


Accessing the QGIS API documentation

The QGIS project hosts comprehensive Python API documentation covering classes like iface and QgsMapLayer. Having the docs open alongside notebooks enables rapid prototyping and exploration:

https://qgis.org/pyqgis/master

Exploring layers and attributes in notebooks

With access to iface, investigating interfaces and project contents is straightforward via notebooks without creating GUI test code. For example, print names and attribute tables:


layers = iface.mapCanvas().layers()

for layer in layers:
print(layer.name())
print(layer.pendingFields().names())


Developing Plugins Within the Environment

Modifying an existing plugin template

The combined OSGeo4W and Conda stack truly shines when building production-grade QGIS plugins. Clone an existing plugin template from the QGIS Plugin Repository as a starting point. Edit actions via an IDE like VS Code to add custom processing algorithms, UI panels, mesh generators, and more.

Testing directly against QGIS desktop

Iteratively improve plugins by loading into QGIS Desktop with Plugin Reloader active for live refresh on save. Click interfaces, configure options, and trigger processing tasks while debugging code or stepping through lines.

Deploying plugins to production instance

Transition vetted plugins from the development environment out to downstream testing and production systems. Export entire Conda envs, IPY kernel configurations, and custom plugin zips to replicate working stacks across Windows machines precisely.

Additional Tips for Managing Environments

Creating multiple Conda envs for different projects

Scale development efforts horizontally by launching additional focused Conda environments with:

conda create --clone my_qgis_env --name my_qgis_env_2

New environments inherit the parent configurations without interference allowing clean parallel workflows.

Upgrading QGIS versions without disrupting workflows

Adjust OSGeo4W selections or standalone QGIS installations independently from Conda envs without impacting Python packages or configs. Then selectively upgrade Conda packages after vetting upstream changes.

Best practices for environment portability

Export entire Conda directory structures along with .condarc files, custom QGIS plugin folders, IPython kernels, and Jupyter notebooks. Archive copies simplify recreation of working states across windows systems and team distributions.