Setting up PyQGIS3 with VSCode & Python3 on Windows

ModuleNotFoundError: No module named 'qgis'

This error got you down? Here’s how I solved it in my vscode and Python and QGIS environment on Windows.

---

This blog post by Gary is excellent for building a development environment for PyQGIS on Windows: Quick Guide to Getting Started with PyQGIS3 On Windows (Spatialgalaxy.net).

In this post we put a slight twist on it, just to be different, and to learn to use Visual Studio Code, on Windows, and without external setup scripts. There were multiple issues that held me back on it this but ultimately it was just my knowledge of vscode that needed an upgrade.

In a nutshell, for a minimal working example, you need four components: a QGIS install, a vscode workspace file, a .env file, and a Python script in the same folder.

QGIS install

In this case, I use a standard release installer from QGIS.org to get set up on Windows (not OSGeo4W). The install location is on a secondary drive, not the long file name with a couple of spaces – that is not a concern with this approach.

Note that the Python modules for both PyQGIS, PyQT5 are included in this install! More below on that.

D:\Program Files\QGIS 3.12\

vscode workspace

I’ve worked on various development projects with vscode before and never worried much about this workspace concept with them.

If you create a file by hand, it will then allow you to open the folder as a workspace. I suggest creating all the files below first, then opening it in vscode (File-> Open Folder).

If you do not have one of these JSON format files already, it will prompt you to create/save one. The one it created for me wasn’t very helpful as it had the wrong paths in it and it messed me up further.

Here is my workspace definition file, saved in:

c:\users\tyler\source\repos\diy-gis\workspace.code-workspace

{
   "folders": [
      {
         "name": "app",
         "path": "C:\Users\tyler\source\repos\diy-gis"
      }
   ]
}

All the file does is define the path for the rest of the project. This seems important when you go to launch the Python script,we didn’t worry about any other settings in this file when doing my testing. But it doesn’t mean it’s good enough for further uses especially build/deploy scenarios.

vscode .env file

The .env file is used to set environment variables before running a Python project in a vscode. It appears to require a workspace to be defined as well, see above.

Common system-wide/global Windows environment settings should work but I wanted this to all be self-contained in a single project workspace.

In the .env file, we simply put two lines, one for the PATH and one for the PYTHONPATH to point to our QGIS installation. Adjust for your version and path.

PATH=$PATH;"D:\Program Files\QGIS 3.18\bin\";"D:\Program Files\QGIS 3.18\apps\qgis\bin"
PYTHONPATH="D:\Program Files\QGIS 3.12\apps\qgis\python"

Basic Python app with QGIS module loaded

As we were early in this project let’s ensure that PyQT5 and QGIS modules would load into the Python project.

In the QGIS appsqgispython folder are the modules that Python will use, per the .env file above.

Some places will tell you to install PyQT5 with pip and that is not necessary if you have things set up this way. Plus you’ll know that your versions of QT and PyQGIS will be compatible if you use the same location for the modules.

This code uses both those modules and builds a very basic Hello World app. The file is app1.py in my workspace.

import sys
import qgis

from PyQt5.QtWidgets import QApplication, QWidget, QLabel

def window():
   app = QApplication(sys.argv)
   widget = QWidget()

   textLabel = QLabel(widget)
   textLabel.setText("Hello World!")
   textLabel.move(110,85)

   widget.setGeometry(50,50,320,200)
   widget.setWindowTitle("PyQt5 Example")
   widget.show()
   sys.exit(app.exec_())

if __name__ == '__main__':
   window()

Next, with the app1.py open in vscode, I run the app script from the Run -> Run Without Debugging tool and see the application window pop up!

If things go wrong, check the terminal/console for any errors, here is my terminal output from vscode:

PS C:\Users\tyler\source\repos\diy-gis>  c:; cd 'c:\Users\tyler\source\repos\diy-gis'; & 'C:\python38\python.exe' 'c:\Users\tyler\.vscode\extensions\ms-python.python-2021.10.1365161279\pythonFiles\lib\python\debugpy\launcher' '54781' '--' 'c:\Users\tyler\source\repos\diy-gis\app1.py' 

If I comment out the PYTHONPATH from the .env file, I get my errors finding the PyQGIS module: qgis. Note that I do not get errors for PyQt because I also had them installed by pip in my main Python installation.

Traceback (most recent call last):
  File "c:\Users\tyler\source\repos\diy-gis\app1.py", line 2, in <module>
    import qgis
ModuleNotFoundError: No module named 'qgis'
PS C:\Users\tyler\source\repos\diy-gis>

Resources

• Zipped workspace files of the above project
• PyQGIS3 Programmer’s Guide book/e-book from Locate Press
• Spatialgalaxy post for examples that work well with PyCharm
• Follow us on LinkedIn and Twitter
• Register for our mailing list to get sales/discounts and updates