Installing KiCad and using its Python API (GUI, console, headless)
Install KiCad, run your first scripts from the interface's console or the command line, and learn how pcbnew and the IPC API both work headless.
Before scripting a single footprint, you need KiCad installed and a clear idea of where your Python scripts actually run. This tutorial covers installation, then the three ways to run code against a board: from the interface, from the command line with the GUI closed, and — often misunderstood — headless with the IPC API.
Installing KiCad
Download the installer from kicad.org: .exe on Windows, .dmg on macOS, your distribution’s package or a Flatpak on Linux. Grab the latest stable release — KiCad 10/11 is recommended if you plan to use the IPC API, introduced with these versions.
The IPC API needs to be explicitly enabled: in KiCad’s preferences, under Plugins and IPC API, check the option that allows external scripts to connect. pcbnew, the long-standing C++ binding, needs no such activation — it’s available right after installation.
Using the API from KiCad’s interface
In pcbnew, open Tools → Scripting Console. It’s an interactive Python interpreter with direct access to the currently open board:
import pcbnew
board = pcbnew.GetBoard()
print(board.GetFileName())With the IPC API enabled, an external script (in your editor, a terminal, a notebook) connects to the already-running KiCad instance, with no need for a built-in console:
from kicad import KiCad
kicad = KiCad()
board = kicad.get_board()
print(board.name)Using the API from the command line, with no interface
pcbnew also works fully headless: no KiCad process is needed at all — the Python module loads the .kicad_pcb file directly in memory, inside your own script:
import pcbnew
board = pcbnew.LoadBoard("my_board.kicad_pcb")
# ... modifications ...
pcbnew.SaveBoard("my_board.kicad_pcb", board)This is the basis for most CI pipelines that validate or modify boards automatically.
The IPC API stays a client/server model even with no GUI: a KiCad process still needs to run in the background to answer requests. You launch it headless, then connect to it exactly as in this site’s other tutorials:
from kicad import KiCad
kicad = KiCad()
board = kicad.get_board()
# ... same calls as in the footprint, via, and zone tutorials ...Unlike pcbnew headless, there’s always a KiCad process running in the background here — it’s simply not showing a window.
Going further
Once the environment is set up, the following tutorials show how to script each concrete layout step — footprint placement, via creation, copper zones — with both APIs.