KiCad en headless : scripts Python et kicad-cli sans interface

Publié le 18 octobre 2026 par leZ

Modifiez une board, lancez le DRC et exportez Gerber et perçage sans ouvrir KiCad : pcbnew en headless, kicad-cli et codes de sortie pour la CI.

Terminal : kicad-cli pcb drc renvoie le code de sortie 0 sur une board propre et 5 sur une board avec une violation DRC — kicad-cli pcb drc : code de sortie 0 si la board est propre, 5 s'il y a une violation.

« Headless », c’est faire travailler KiCad sans ouvrir son interface : sur un serveur d’intégration continue, dans un script de fabrication, ou pour traiter cinquante boards d’un coup. Deux outils se complètent : un script Python qui modifie la board, et kicad-cli qui vérifie et exporte. Toutes les commandes de cette page ont été lancées telles quelles sous Windows avec KiCad 10.0.

Modifier une board sans interface

Avec pcbnew, aucun process KiCad n’est nécessaire : le module charge le fichier .kicad_pcb en mémoire, vous le modifiez, puis vous le réenregistrez. Exemple qui remplit à nouveau toutes les zones :

import pcbnew

board = pcbnew.LoadBoard("demo.kicad_pcb")
for zone in board.Zones():
    zone.SetLocalClearance(pcbnew.FromMM(0.3))
pcbnew.ZONE_FILLER(board).Fill(board.Zones())
pcbnew.SaveBoard("demo.kicad_pcb", board)
print("zones refilled:", len(board.Zones()))

Lancez-le avec le Python fourni avec KiCad ("C:\Program Files\KiCad\10.0\bin\python.exe" refill_zones.py), sinon import pcbnew échoue : voir l’erreur No module named ‘pcbnew’.

⚠️ Testé : pcbnew.WriteDRCReport() fonctionne dans la console de KiCad, mais plante dans un script Python autonome (KiCad 10.0.6). En headless, lancez le DRC avec kicad-cli (ci-dessous).

L’API IPC reste un modèle client/serveur : il faut un process KiCad pour répondre. En headless, kipy peut le démarrer lui-même via kicad-cli :

from kipy import KiCad

with KiCad(headless=True, file_path="demo.kicad_pcb") as kicad:
    board = kicad.get_board()
    # ... mêmes appels qu'avec KiCad ouvert ...

⚠️ Testé : headless=True demande KiCad 11 (ou les nightlies 10.99) et kicad-python 0.9.0 ou plus. Sur KiCad 10 stable, utilisez pcbnew ou kicad-cli. Détails dans le tutoriel d’installation.

Lancer le DRC et faire échouer la CI

kicad-cli est livré avec KiCad (dans le même dossier bin). Avec --exit-code-violations, le DRC renvoie un code de sortie différent de 0 dès qu’il trouve une violation — exactement ce qu’attend un pipeline de CI pour bloquer une modification :

kicad-cli pcb drc --exit-code-violations -o drc.rpt demo.kicad_pcb

Résultat réel sur une board propre (code 0), puis sur une copie à laquelle on a ajouté une piste qui viole une règle (code 5) : voir la capture en haut de page. Options utiles : --format json pour un rapport exploitable par un script, --severity-all pour inclure les avertissements, --refill-zones pour remplir les zones avant la vérification.

Exporter les Gerber et le perçage

kicad-cli pcb export gerbers --layers F.Cu,B.Cu,F.Mask,B.Mask,F.Silkscreen,Edge.Cuts -o fab/ demo.kicad_pcb
kicad-cli pcb export drill -o fab/ demo.kicad_pcb

kicad-cli pcb export gerbers et export drill en ligne de commande : six fichiers Gerber et un fichier de perçage générés — Six couches Gerber et le fichier de perçage, générés sans ouvrir KiCad.

Sans --layers, kicad-cli exporte toutes les couches de la board, y compris les couches User et Fab dont le fabricant n’a pas besoin.

Générer une image 3D de la board

Pratique pour une documentation ou un aperçu automatique dans une pull request :

kicad-cli pcb render -o board3d.png -w 1600 -h 1000 --quality high --perspective --rotate -38,0,18 demo.kicad_pcb

Rendu 3D d'une board KiCad généré en ligne de commande par kicad-cli pcb render, sans ouvrir l'interface — Image générée par kicad-cli pcb render (environ 7 s en qualité high).

Pour aller plus loin

Le même enchaînement — script Python qui modifie, kicad-cli qui vérifie puis exporte — se transpose tel quel dans GitHub Actions ou GitLab CI. Pour piloter un KiCad déjà ouvert depuis un script externe, voyez comment activer l’API IPC.