Creating a stitching-via grid with pcbnew's Python API

Published on September 13, 2026 by leZ

Generate a full grid of ground-connected stitching vias by script, instead of one via at a time — with pcbnew or KiCad's IPC API.

Grid of 4 × 4 GND stitching vias at a 5 mm pitch, generated by a Python script in KiCad
The grid of 16 GND vias, 5 mm apart.

The via creation tutorial places a single one. A stitching-via grid — tied to ground all around a copper pour to improve HF current return — is built with the same API, inside a double loop over rows and columns.

Looping over rows and columns

Each via is created, positioned, and connected to the net within the same iteration:

import pcbnew

board = pcbnew.GetBoard()
from pcbnew import PCB_VIA, VECTOR2I, FromMM

rows, cols, spacing = 4, 4, 5  # mm
gnd = board.FindNet("GND")

for row in range(rows):
    for col in range(cols):
        via = PCB_VIA(board)
        via.SetPosition(VECTOR2I(FromMM(20 + col * spacing), FromMM(20 + row * spacing)))
        via.SetWidth(via.TopLayer(), FromMM(0.6))
        via.SetDrill(FromMM(0.3))
        via.SetNet(gnd)
        board.Add(via)

Same loop structure on the IPC API side: position is set in millimeters, but diameter and drill size are raw nanometers that need converting with from_mm. Each via is a brand-new object, so it’s created on the board with create_items:

from kipy import KiCad
from kipy.board_types import Via, Net
from kipy.geometry import Vector2
from kipy.util.units import from_mm

board = KiCad().get_board()

rows, cols, spacing = 4, 4, 5  # mm
gnd = Net(name="GND")

for row in range(rows):
    for col in range(cols):
        via = Via()
        via.position = Vector2.from_xy_mm(20 + col * spacing, 20 + row * spacing)
        via.diameter = from_mm(0.6)
        via.drill_diameter = from_mm(0.3)
        via.net = gnd
        board.create_items(via)

Try it below: adjust rows, columns, and spacing to see the via grid recompute.

rows, cols, spacing = 3, 4, 5  # mm

for row in range(rows):
    for col in range(cols):
        via.SetPosition(VECTOR2I(FromMM(20 + col * spacing), FromMM(20 + row * spacing)))
3
4
5

Going further

For stitching that’s actually useful in practice, vias are usually only placed inside the outline of an existing copper zone — a point-in-polygon test before each board.Add(via) is enough to filter the grid down to the ground plane’s real shape.