Corriger « ModuleNotFoundError: No module named 'pcbnew' » avec KiCad

Votre script fonctionne parfaitement dans la console de scripts de KiCad, mais dès que vous le lancez depuis un terminal ou depuis VS Code, Python s’arrête net sur la première ligne :

Toutes les solutions ci-dessous ont été testées sous Windows avec KiCad 10.0 (Python 3.11.5 intégré), avec exactement les commandes visibles sur les captures.

Pourquoi import pcbnew échoue

pcbnew n’est pas un paquet pip ordinaire. C’est un module natif compilé avec KiCad (un fichier pcbnew.py et une bibliothèque compilée _pcbnew), installé dans le dossier de KiCad — sous Windows dans C:\Program Files\KiCad\10.0\bin\Lib\site-packages. Il est compilé pour une seule version de Python : celle fournie avec KiCad.

Le Python de votre système (ici 3.13) ne cherche pas dans ce dossier, d’où No module named 'pcbnew'. Inutile non plus de tenter pip install pcbnew : aucun paquet PyPI ne donne accès à l’API de KiCad, le module n’existe qu’avec une installation de KiCad.

Solution 1 : lancer le script avec le Python fourni avec KiCad

La solution la plus fiable : appeler explicitement l’interpréteur de KiCad.

"C:\Program Files\KiCad\10.0\bin\python.exe" mon_script.py

L’interpréteur équivalent sur les autres systèmes (emplacements d’installation standard, non testés sur cette machine) :

• macOS : /Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3
• Linux : le paquet de la distribution installe pcbnew pour le Python du système, utilisez donc /usr/bin/python3 — pas un Python pyenv ou Conda d’une autre version.

Solution 2 (Windows) : ouvrir l’« invite de commandes KiCad »

KiCad installe dans le menu Démarrer un raccourci nommé KiCad 10.0 Command Prompt. Il ouvre un terminal où le dossier bin de KiCad passe en premier dans le PATH : les commandes python et pip visent alors l’installation de KiCad, sans rien taper en entier.

Pratique pour installer un paquet supplémentaire pour vos scripts : pip install ... depuis cette invite l’installe pour le Python de KiCad, pas pour celui du système.

Piège : ajouter le dossier de KiCad au sys.path d’un autre Python

Le raccourci tentant — sys.path.append(r"C:\Program Files\KiCad\10.0\bin\Lib\site-packages") depuis votre Python habituel — remplace l’erreur par une autre :

pcbnew.py est bien trouvé, mais la partie compilée _pcbnew ne se charge que dans la version de Python pour laquelle elle a été construite. Même version de Python que KiCad, ou rien.

Solution 3 : un venv qui voit pcbnew

Vous voulez un environnement virtuel pour vos dépendances ? Créez-le à partir du Python de KiCad avec l’option --system-site-packages, sinon le venv est isolé et ne voit pas non plus pcbnew :

"C:\Program Files\KiCad\10.0\bin\python.exe" -m venv --system-site-packages venv-kicad
venv-kicad\Scripts\python mon_script.py

Dans VS Code, sélectionnez ensuite ce venv (ou directement le python.exe de KiCad) avec Python: Select Interpreter, pour que le bouton Exécuter et l’autocomplétion utilisent le bon interpréteur.

Solution 4 : passer à l’API IPC, compatible avec n’importe quel Python

Depuis KiCad 9, l’API IPC offre une autre voie : son client Python, kipy, est un paquet pip classique (pip install kicad-python) qui dialogue avec un KiCad ouvert via un socket. Plus besoin du Python de KiCad — mais KiCad doit être lancé avec l’API activée. La mise en place et les différences avec pcbnew sont détaillées dans le tutoriel d’installation.

Récapitulatif

Situation	Solution
ModuleNotFoundError dans un terminal	Lancer le script avec C:\Program Files\KiCad\10.0\bin\python.exe
Windows, commandes python/pip	Ouvrir KiCad 10.0 Command Prompt
DLL load failed while importing _pcbnew	Mauvaise version de Python : utiliser celle de KiCad, ne pas bricoler sys.path
Environnement virtuel	venv --system-site-packages, créé depuis le Python de KiCad
Vous préférez votre propre Python	API IPC (pip install kicad-python)