Installer KiCad et utiliser son API Python (interface, console, headless)

pcbnew, la liaison C++ historique, ne nécessite aucune activation particulière : elle est disponible dès l’installation.

C’est aussi un module natif compilé pour un interpréteur précis : il n’existe que dans l’arborescence de KiCad, pas dans votre Python système. Pour qu’import pcbnew fonctionne en dehors de la console intégrée, il faut exécuter vos scripts avec le Python fourni avec KiCad, situé dans le bin/ du dossier d’installation — par exemple sous Windows :

C:\Program Files\KiCad\<version>\bin\python.exe

Lancez vos scripts avec cet exécutable ("C:\Program Files\KiCad\10.0\bin\python.exe" mon_script.py), ou pointez l’interpréteur de votre IDE/venv dessus. Le principe est le même sous macOS et Linux : si le Python de votre système ne trouve pas pcbnew, cherchez celui livré avec votre installation KiCad.

Vous obtenez ModuleNotFoundError: No module named 'pcbnew' ? Toutes les causes et leurs solutions sont dans ce guide dédié.

L’API IPC doit être activée explicitement : dans Préférences → Préférences…, ouvrez la page Plugins (1) et cochez Activer l’API KiCad (2).

kipy, le client Python de l’API IPC, est un paquet pip classique — installable dans n’importe quel environnement Python, sans avoir besoin du Python intégré à KiCad :

pip install kicad-python

Le paquet PyPI s’appelle kicad-python, mais s’importe sous le nom kipy.

Dans pcbnew, ouvrez Outils → Console de Script (1), ou cliquez sur le bouton console à droite de la barre d’outils (2). C’est un interpréteur Python interactif avec un accès direct à la board actuellement ouverte :

import pcbnew

board = pcbnew.GetBoard()
print(board.GetFileName())

Avec l’API IPC activée, un script externe (dans votre éditeur, un terminal, un notebook) se connecte à l’instance de KiCad déjà ouverte, sans passer par une console intégrée — et sans avoir besoin du Python fourni avec KiCad : kipy communique par socket, donc n’importe quel Python où kicad-python est installé fonctionne, du moment que KiCad tourne avec l’interface ouverte et l’API activée dans les préférences :

from kipy import KiCad

kicad = KiCad()
board = kicad.get_board()
print(board.name)

⚠️ Rappel : ce code doit toujours être exécuté avec le Python intégré à KiCad (voir plus haut), pas votre Python système — pcbnew n’est importable que depuis cet interpréteur, même en headless. Sous Windows, le plus simple est le raccourci KiCad 10.0 Command Prompt du menu Démarrer : dans ce terminal, python et pip désignent l’installation de KiCad.

pcbnew s’utilise aussi entièrement headless : aucun process KiCad n’est nécessaire, le module Python charge directement le fichier .kicad_pcb en mémoire dans votre propre script :

import pcbnew

board = pcbnew.LoadBoard("ma_carte.kicad_pcb")
# ... modifications ...
pcbnew.SaveBoard("ma_carte.kicad_pcb", board)

C’est la base de la plupart des pipelines CI qui valident ou modifient des boards automatiquement.

L’API IPC reste un modèle client/serveur, même sans interface graphique : un process KiCad doit tourner en arrière-plan pour répondre aux requêtes. Plutôt que de vous connecter à une instance déjà ouverte, vous demandez cette fois à kipy de démarrer lui-même ce process headless via kicad-cli, avec headless=True :

from kipy import KiCad

with KiCad(headless=True, file_path="ma_carte.kicad_pcb", kicad_cli_path=None) as kicad:
    board = kicad.get_board()
    # ... mêmes appels que dans les tutoriels footprint, via et zone ...

with ferme proprement la connexion et arrête le process headless à la sortie du bloc, même en cas d’erreur — préférez cette forme à un appel manuel à kicad.close().

kicad_cli_path est optionnel : laissé à None, kicad-python cherche kicad-cli tout seul dans l’installation KiCad standard (ou dans le PATH) ; ne le renseignez que si votre installation est à un emplacement non standard, en lui passant le chemin complet vers l’exécutable kicad-cli.

Contrairement à pcbnew headless, il y a donc toujours un process KiCad actif en arrière-plan — simplement sans fenêtre visible.

⚠️ Deux conditions de version, vérifiées en local avant d’écrire ces lignes :

• côté KiCad, headless=True ne fonctionne qu’à partir de KiCad 11 ou des nightly 10.99 — la sous-commande kicad-cli api-server n’existe pas encore dans KiCad 10 stable ;
• côté bibliothèque, ces paramètres (headless, file_path, kicad_cli_path) n’existent qu’à partir de kicad-python 0.9.0, encore en développement au moment de la rédaction : un pip install kicad-python classique installe aujourd’hui la 0.8.0, qui lève TypeError: unexpected keyword argument 'headless'. Vérifiez votre version installée (pip show kicad-python) avant de copier ce code tel quel, et attendez-vous à devoir mettre à jour kicad-python une fois une release incluant ces paramètres publiée.