Créer un environnement virtuel Python pour le développement de plugin QGIS avec VS Code sous Windows#

Date de publication initiale : 25 novembre 2024

Introduction#

Tout ceux qui s'y sont frottés le savent, configurer son environnement Python, PyQGIS et PyQt sous Windows pour développer des plugins pour QGIS est un réel parcours du combattant. À la fin, on est souvent perdant...

Et bien, plus maintenant ! Après avoir fouillé les archives d'internet et exploré les pistes fournies par Julien, voici l'une des méthodes permettant d'avoir toutes (ou presque) les autocomplétions d'objets et méthodes PyQGIS, PyQt, etc. dans VS Code.

Commenter cet article

Création de l'environnement virtuel#

Je suppose dans la suite que vous avez installé QGIS dans le répertoire C:\OSGeo4W (la procédure est identique que QGIS soit installé via l'installateur réseau OSGeo4W ou via le package MSI, les chemins indiqués dans la suite de l'article sont simplement à adapter selon votre installation).

1. Ouvrir une console OSGeo4W Shell et naviguer jusqu'à l'emplacement où vous souhaitez créer l'environnement virtuel.
   Par exemple, un template de plugin fraîchement créé via l'outil QGIS Plugin Templater.

2. Exécuter les commandes suivantes :

   Création d'un environnement virtuel dans l'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
   

   L'option --system-site-packages permet à l'environnement virtuel créé d'hériter des librairies spécifiques à l'environnement Python dans QGIS.

3. Pour que VSCode reconnaisse les imports processing, ajouter la ligne suivante dans le fichier .venv\qgis.pth :
   C:\OSGeo4W\apps\qgis\python\plugins

   Votre fichier devrait ressembler à ça :

   Contenu du fichier .venv\qgis.pth

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

   Veiller à ce que l'encodage du fichier .venv\qgis.pth soit bien en UTF-8.

4. Créer le fichier sitecustomize.py dans le dossier .venv\Lib\site-packages avec le contenu suivant :

   .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. Dans le fichier .venv\pyvenv.cfg, modifier les occurences C:\OSGeo4W\bin en 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 <Le chemin complet vers votre venv>
   

Avec l'utilitaire qgis-venv-creator#

Paragraphe ajouté en janvier 2025

Juste après que cet article soit publié, on découvrait le projet create-qgis-venv de GispoCoding.

Il se présente comme un outil en ligne de commande (CLI) multi-plateforme. Il est recommandé de l'installer avec pipx qui gère la plupart des paramètres un peu sioux et qui est compatible avec Windows. C'est désormais l'outil recommandé dans la communauté Python pour gérer les outils en ligne de commande (CLI), c'est donc une bonne occasion de s'y mettre. Une fois pipx installé, paramétré (ensurepath...) et une nouvelle session PowerShell lancée, l'installation se passe comme un charme :

pipx install qgis-venv-creator

L'outil qgis-venv-creator est désormais accessible depuis n'importe quelle session PowerShell avec la commande suivante :

create-qgis-venv --venv-name ".venv"

L'outil a besoin d'identifier l'installation de QGIS à utiliser pour la génération de l'environnement de développement et cherche dans les emplacements par défaut (C:\OSGeo4W et C:\PROGRAMFILES\QGIS X.y.z). Mais si vous êtes quelqu'un de bien, soigneux et utilisez QGIS dans un monde professionnel, vous l'installez probablement dans un emplacement correct au regard de ce que recommande le système d'exploitation, %PROGRAMFILES%/QGIS/X_y par exemple. Il est possible de passer un pattern pour lui indiquer où chercher :

create-qgis-venv --qgis-installation-search-path-pattern "C:\Program Files\QGIS\*\apps\qgis*" --venv-name ".venv"

Il suffit d'activer son environnement virtuel .venv/Scripts/activate et de continuer ce tutoriel !
Merci Gispo !

Dans VS Code#

Si vous ouvrez VS Code dans le dossier où vous venez de créer l'environnement virtuel, VS Code détectera automatiquement l'environnement (sinon installer l'extension VS Code Python) et lorsque vous taperez des bouts de code, VS Code vous proposera les objets ou méthodes PyQGIS.

Pour également avoir l'ensemble des complétions associées à PyQt, il semble être nécessaire d'installer une librairie Python supplémentaire PyQt5-stubs (certes qui n'est plus maintenue mais qui a le mérite de fonctionner).
Dans le terminal VS Code, exécuter la commande :

pip install PyQt5-stubs

Tout ça pour avoir un code coloré !

Auteur·ices#

Nicolas Godet#

Ingénieur hydraulicien de formation, les SIG et QGIS font parti de mon quotidien tout comme les équations de Navier-Stockes, fameuses équations aux dérivées partielles non linéaires qui décrivent le mouvement des fluides newtoniens.

Esprit bidouilleur, je me suis rapidement tourné vers Python et PyQGIS pour le développement de scripts métier d'automatisation de traitement de résultats de modèle numérique puis le développement et maintien de plugins QGIS.

Julien MOURA#

Géographe "sigiste" de formation, j'ai travaillé sur différentes thématiques et types de structures : gestion des déchets en milieu urbain à Madagascar, foncier d'intérêt général auprès de l'EPF de La Réunion, organisation et la résilience urbaine face aux risques naturels à Lima pour l'IRD, gouvernance et ouverture des données à Isogeo.

Je travaille désormais à Oslandia.
Féru des dynamiques de contributions, je participe activement à Geotribu depuis fin 2011.

Licence Beerware #

Ce contenu est sous licence Beerware (Révision 42).
Les médias d'illustration sont potentiellement soumis à d'autres conditions d'utilisation.

Commentaires