Setting a copper zone's thermal relief with pcbnew's Python API

Published on September 21, 2026 by leZ

Configure the thermal relief around pads connected to a copper zone, by script — with pcbnew or KiCad's IPC API.

A pad soldered directly into a large copper plane absorbs a huge amount of heat, which makes hand soldering difficult. Thermal relief connects the pad to the zone through thin spokes instead of a solid connection, to limit that heat dissipation.

Configuring the thermal relief

The gap and spoke width are set separately on the zone:

zone.SetThermalReliefGap(FromMM(0.3))
zone.SetThermalReliefSpokeWidth(FromMM(0.25))

Same settings, exposed as properties directly in millimeters:

zone.thermal_relief_gap = 0.3
zone.thermal_relief_spoke_width = 0.25
board.update_items(zone)

Try it below: adjust the gap to see the insulating ring around the pad change.

zone.SetThermalReliefGap(FromMM(0.3))

Thermal relief gap (mm)

0.30

Going further

Too small a gap doesn’t solve the dissipation problem; too large weakens the connection mechanically. For a power pad that instead needs to dump heat efficiently, it’s often better to disable thermal relief entirely (a solid connection) rather than tune one.