Resolving Importerrors When Using Pyqgis In Standalone Scripts On Windows

Locating QGIS Python Modules

When writing standalone Python scripts that utilize the PyQGIS libraries, the QGIS Python modules must be accessible to the Python interpreter. On Windows systems, these modules reside within the OSGeo4W Python installation that comes bundled with QGIS.

Specifically, the PyQGIS modules are located in the “python” subdirectory within the OSGeo4W home path, which is typically C:\OSGeo4W. For example:

C:\OSGeo4W\apps\Python37\python\qgis

Table of Contents

This directory contains all the PyQGIS libraries and modules, like qgis.core, qgis.analysis, qgis.utils, and more. Understanding where these modules live is key to configuring Python to locate them properly when running standalone scripts.

Setting the PYTHONPATH Environment Variable

In order for Python to locate the QGIS modules, the PYTHONPATH environment variable needs to be set correctly to include the path of the PyQGIS libraries shown above. PYTHONPATH is an environment variable that tells Python where to search for imported modules on the filesystem.

To configure PYTHONPATH permanently on Windows:

Open the System Properties dialog
Click the Advanced tab, then Environment Variables
Under System Variables, click New if PYTHONPATH does not exist
For Variable Name, enter PYTHONPATH
For Variable Value, enter the path of OSGeo4W’s PyQGIS modules, e.g. C:\OSGeo4W\apps\Python27\python\qgis
Click OK to save

Now Python will check this path when importing PyQGIS modules. A system restart may be required for changes to take effect.

Verifying the PYTHONPATH Configuration

With PYTHONPATH configured, we can test this by opening Python from the OSGeo4W shell and attempting to import some PyQGIS modules.

To open the OSGeo4W shell, navigate Start Menu -> OSGeo4W -> OSGeo4W Shell. Then type python to open Python:


Microsoft Windows [Version XX.X.XXXXX]
(c) 20XX Microsoft Corporation. All rights reserved.

C:\Users\username>OSGeo4W.bat

OSGeo4W home is C:\OSGeo4W

C:\OSGeo4W>python
Python 3.7.5 (default, May 11 2022, 08:44:39) 
[GCC 10.3.0] :: Anaconda, Inc. on linux
Type "help", "copyright", "credits" or "license" for more information.  
>>> import qgis.core
>>>

If no errors occur when importing qgis.core (or any other PyQGIS module), then PYTHONPATH is configured correctly and Python is able to locate the modules.

Example Code for Importing and Using PyQGIS Modules

With a valid PYTHONPATH in place, PyQGIS modules can now be imported into any Python script using import statements, whether run from the terminal, an IDE, or a Jupyter notebook.

For example, here is some sample code to load a layer and print its name:


import qgis.core

# Supply path to layer
layer_path = "/path/to/layer.shp"  

# Create layer instance
layer = qgis.core.QgsVectorLayer(layer_path, "layer_name", "ogr")

# Print layer name
print(layer.name())

This script imports the qgis.core module, loads a vector layer using it, and prints the layer’s name – all made possible by having Python properly configured to discover the PyQGIS modules.

Common ImportError Causes and Solutions

There are a few common issues that can prevent PyQGIS modules from being imported properly even after setting PYTHONPATH. Some things to check:

Missing OSGeo4W Installation

PYTHONPATH will be ineffective if QGIS and its accompanying Python environment is not installed via OSGeo4W in the first place. Ensure QGIS has been installed through the OSGeo4W interactive installer.

Incorrect PYTHONPATH Variable

Double check that the PYTHONPATH variable targets the correct directory where the PyQGIS modules reside. Pay special attention to the Python version folder (e.g. Python37). An incorrect path will fail to resolve modules.

Conflicts with Other Python Installations

Standalone Python installations can sometimes conflict with OSGeo4W’s Python, causing unexpected issues when running scripts. Try running scripts using OSGeo4W’s Python rather than another Python instance.

Testing PyQGIS Module Imports

One way to continually test that PyQGIS modules are importable is to create a simple test script. For example, save the following as test_imports.py:


import qgis.core
import qgis.analysis
import qgis.utils

print("Imports successful!")

Then run this script from the OSGeo4W shell Python prompt, or by calling it directly with OSGeo4W’s python.exe interpreter. This serves as an easy test to verify things continue working as expected.

Ensuring QGIS Libraries are Available to Python

In addition to PyQGIS modules, QGIS relies on various backend libraries and dependencies written in C/C++. Python scripts loading QGIS modules rely indirectly on these libraries being locatable at runtime.

On Windows, OSGeo4W uses PATH environment variable to track the locations of required .DLL files and libraries. So once again, running Python scripts from within the OSGeo4W shell will ensure the correct PATH is inherent.

Using OSGeo4W’s Python guarantees all the pieces are in place – PYTHONPATH, PATH, library dependencies – for seamless PyQGIS scripting and utilization of all QGIS capabilities.