Creating a Python virtual environment for developing QGIS plugin with VS Code on Windows

Introduction

Anyone who has tried it, knows that configuring a Python, PyQGIS, and PyQt environment on Windows for developing QGIS plugins is a real challenge. Often, it feels like a losing battle...

Well, not anymore! After scouring the depths of the internet and exploring tips provided by Julien, here is one method to have (almost) all the auto-completions for PyQGIS, PyQt and more in VS Code.

Leave a comment

---

Creating the Virtual Environment

I will assume that you have installed QGIS in the C:\OSGeo4W directory (the procedure is the same whether QGIS is installed via the OSGeo4W network installer or the MSI package; the paths in this article just need to be adapted to your installation).

1. Open an OSGeo4W Shell and navigate to the location where you want to create the virtual environment.
   For example, a freshly created plugin template using the QGIS Plugin Templater.

2. Run the following commands:

   Creating a virtual environment in the OSGeo4W Shell

   C:\OSGeo4W\bin\python-qgis.bat -m venv --system-site-packages .venv
   C:\OSGeo4W\bin\python-qgis.bat -c "import pathlib;import qgis;print(str((pathlib.Path(qgis.__file__)/'../..').resolve()))" > .venv\qgis.pth
   

   The --system-site-packages option allows the virtual environment to inherit libraries specific to the Python environment in QGIS.

3. To ensure VS Code recognizes processing imports, add the following line to the .venv\qgis.pth file:
   C:\OSGeo4W\apps\qgis\python\plugins

   Your file should look like this:

   Content of .venv\qgis.pth file

   C:\OSGeo4W\apps\qgis\python
   C:\OSGeo4W\apps\qgis\python\plugins
   

   Make sure the encoding of the .venv\qgis.pth file is set to UTF-8.

4. Create a sitecustomize.py file in the .venv\Lib\site-packages folder with the following content:

   .venv\Lib\site-packages\sitecustomize.py

   import os
   
   os.add_dll_directory("C:/OSGeo4W/bin")
   os.add_dll_directory("C:/OSGeo4W/apps/qgis/bin")
   os.add_dll_directory("C:/OSGeo4W/apps/Qt5/bin")
   

5. In the .venv\pyvenv.cfg file, modify the occurrences of C:\OSGeo4W\bin to C:\OSGeo4W\apps\Python312:

   .venv\pyenv.cfg

   home = C:\OSGeo4W\apps\Python312
   include-system-site-packages = true
   version = 3.12.6
   executable = C:\OSGeo4W\apps\Python312\python.exe
   command = C:\OSGeo4W\apps\Python312\python.exe -m venv --system-site-packages <The full path to your venv>
   

---

In VS Code

If you open VS Code in the folder where you just created the virtual environment, VS Code will automatically detect the environment (otherwise, install the VS Code Python extension), and as you type code, VS Code will suggest PyQGIS objects or methods.

To also have all the completions related to PyQt, it seems necessary to install an additional Python library called PyQt5-stubs (although it is no longer maintained, it still works).
In the VS Code terminal, run the following command:

Install PyQT completion in the virtual environment

pip install PyQt5-stubs

All of this just to have colorful code !

Share it:

Comments