KiCad Tools

List all symbol instances from a root schematic's symbolInstances table. Args: schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.

Get pin info for a symbol in the schematic's lib_symbols. Args: symbol_name: Symbol name (e.g. "LM7805", "C", "Fuse") schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

Get KiCad version information including build details and library versions.

Check if a schematic is the root or a sub-sheet. Args: schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

List all nets that cross sheet boundaries (hierarchical pins and global labels). Args: schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.

List the full sheet hierarchy starting from a root schematic. Args: schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.

List all footprints in a .pretty library directory. Args: pretty_dir: Path to .pretty directory containing .kicad_mod files

List all symbols in a .kicad_sym library file. Args: symbol_lib_path: Path to .kicad_sym file. Optional; omit to use the configured default.

List all footprints on the PCB. Args: pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.

List all graphic items (lines, text, etc.) on the PCB. Args: pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.

List all layers defined in the PCB stackup: copper, silkscreen, soldermask, solder paste, courtyard, fabrication, and the board outline. Which of those a given board actually defines is up to the board. Call this before any tool that takes a layer name, since the valid set is per-board and renamed layers are common. Args: pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.

List all named nets on the PCB. Args: pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.

List all trace segments and vias on the PCB. Args: pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.

List all zones (copper and keepout) on the PCB. Args: pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.

List all bus entries in the schematic. Args: schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

List all placed components in the schematic. Args: schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

List all global labels in the schematic. Args: schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

List all hierarchical labels in the schematic. Args: schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

List all junctions in the schematic. Args: schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

List all net labels in the schematic. Args: schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

List all no-connect flags in the schematic. Args: schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

List all hierarchical sheets in the schematic. Args: schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

List all wire segments in the schematic. Args: schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

List unconnected pins by running ERC and filtering results. Requires kicad-cli. Auto-redirects to root schematic for sub-sheets to avoid false positives from hierarchical label context. Args: schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default. output_dir: Directory for ERC report file. Optional; omit to use the configured default. project_path: Path to .kicad_pro file for explicit root resolution

Modify an existing hierarchical label. Args: text: Current label text to find schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default. new_text: New label text (empty = keep current) new_shape: New shape/direction (empty = keep current) new_x: New X position (None = keep current) new_y: New Y position (None = keep current) uuid: UUID for disambiguation

Modify properties of an existing hierarchical sheet block. Args: sheet_uuid: UUID of the sheet to modify (from list_schematic_sheets) schematic_path: Path to parent .kicad_sch. Optional; omit to use the configured default. sheet_name: New display name (empty = keep) file_name: New file path (empty = keep) width: New width in mm (None = keep) height: New height in mm (None = keep)

Move a placed component to a new position. Args: reference: Reference designator (e.g. "R1") x: New X position y: New Y position rotation: New rotation in degrees (None = keep current) schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

Move a footprint to a new position. A move rewrites the footprint's own position and nothing of its pads, texts or graphics, which KiCad stores relative to the footprint. The zones it owns and a KiCad 10 footprint's points are stored in board coordinates, so they move by the same delta, as KiCad's FOOTPRINT::SetPosition moves them (pcbnew/footprint.cpp:2553-2584 at 9.0.8). A rotation turns the footprint to that angle as KiCad's own rotate turns it: every pad and text turns by the change from the angle it had, its zones and points turn about it, and a keep-upright text that would read upside down is turned half a turn with its justification mirrored, so it stays readable on the same side of its anchor. Angles are written as KiCad writes them: the footprint's between -180 and 180 and left out at 0. Off the quarter turns the result reads as KiCad's turn without matching pcbnew's save byte for byte: footprint-relative coordinates stay as written where pcbnew re-derives them through two RotatePoint roundings, an fp_rect stays where pcbnew writes an fp_poly, and arc mid points stay as written. A footprint carrying what this tool does not move with it (a dimension, image, table or barcode, or a child no KiCad it knows reads) is refused and nothing is written. The keep-out warning reads keepouts as check_placement does. Args: reference: Reference designator (e.g. "R1") x: New X position y: New Y position rotation: The footprint's angle after the move, in degrees (None keeps the current one). An angle the footprint already has (270 for one at -90, 360 for one at 0) changes nothing and leaves the file byte-identical, where KiCad's footprint properties dialog would still re-run its rotate by a full turn. inf and nan are refused and nothing is written. layer: F.Cu or B.Cu (empty keeps the side; anything else is refused). The other side flips the footprint as KiCad's own flip does (FOOTPRINT::Flip, pcbnew/footprint.cpp:2491-2550 at 9.0.8): pads, texts and graphics mirror, their layers go to their opposites on this board (user layers it pairs included), a text's mirror toggles on side-specific layers only, zones and points mirror about the footprint with their layers, and 3D models stay as they are. With a rotation the flip comes first, so rotation names the angle the footprint ends at. Refused, with nothing written: a text box, a pad's own padstack, KiCad 10's back drills, and on a board of four or more copper layers an item (a zone included) on inner copper that does not name every inner layer, which KiCad 9 and 10 flip apart. pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.

Move a hierarchical sheet block to a new position, including all pins. Args: sheet_uuid: UUID of the sheet to move new_x: New X position in mm new_y: New Y position in mm schematic_path: Path to parent .kicad_sch. Optional; omit to use the configured default.

Place a no-connect flag on a component pin. Resolves pin position and places a no-connect flag. Idempotent: calling again for a pin that already has one is a no-op. Args: reference: Component reference (e.g. "U2") pin_name: Pin name (e.g. "NC") or number (e.g. "3") schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

Place a schematic symbol: resistor, capacitor, inductor, diode, LED, transistor, crystal, switch, connector, or an IC such as a microcontroller or regulator chip. Any lib_id in a library works. Args: lib_id: Library identifier (e.g. "Device:R", "Device:C", "MyLib:MyPart") reference: Reference designator (e.g. "R1", "U1") value: Component value (e.g. "10K", "100nF") x: X position in schematic units (mm) y: Y position in schematic units (mm) rotation: Rotation angle in degrees (0, 90, 180, 270) symbol_lib_path: Path to a .kicad_sym file that defines the symbol, for a library outside KiCad's stock set. Optional; omit to load the symbol from the stock library named by the lib_id prefix. mirror: Mirror axis ("x", "y", or "" for none) schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default. project_path: Path to .kicad_pro file (for correct hierarchy resolution in sub-sheets)

Place a footprint on the PCB. Name a library and a footprint to place the real thing: its pads, silkscreen, courtyard and 3D model are copied from the library file exactly as KiCad would place them, a footprint in KiCad 7's form taking the reference and value in its own (fp_text reference|value ...), where one holding %V or %R, which KiCad reads there as a variable, is refused. Without them you get a marker carrying only the reference and value, which has NO PADS and so cannot be routed or checked; that is the older behaviour and it is kept for callers that only want a placeholder. Use list_lib_footprints to see what a library holds. The footprint is turned to its rotation as KiCad's own rotate turns it: every pad and text turns with it (a pad's angle is its library angle plus the footprint's), and a keep-upright text that would read upside down is turned half a turn with its justification mirrored, so it stays readable on the same side of its anchor. Angles are written as KiCad writes them: the footprint's between -180 and 180 and left out at 0, each pad's and text's absolute. Off the quarter turns the result reads as KiCad's placement without matching pcbnew's save byte for byte: footprint-relative coordinates stay as the library writes them where pcbnew re-derives them through two RotatePoint roundings, an fp_rect stays where pcbnew writes an fp_poly, and arc mid points stay as written. A library footprint without a Datasheet or Description field is placed without it, so KiCad reads that hidden field at its default on F.Fab, whereas pcbnew writes it, on B.Fab for a placement on the back. Zones the footprint owns (keepouts, say) and a KiCad 10 footprint's points are stored in board coordinates (format( ZONE ), pcb_io_kicad_sexpr.cpp:2628-2637 at 9.0.8), so they land where KiCad's placement puts them: moved with the footprint, turned about it and, on the back, mirrored with it. A footprint carrying what this tool does not move with it (a dimension, image, table or barcode, or a child no KiCad it knows reads), or on the back what it does not flip (see move_footprint), is refused and nothing is written. Args: reference: Reference designator (e.g. "R2") value: Component value (e.g. "4.7K") x: X position in mm y: Y position in mm rotation: The footprint's angle in degrees, counter-clockwise as seen on screen; any finite value (270 is stored as -90, 360 as 0). inf and nan are refused and nothing is written. layer: F.Cu or B.Cu; any other layer is refused. B.Cu places the footprint flipped as KiCad's own flip does, then turns it to rotation (FOOTPRINT::Flip, pcbnew/footprint.cpp:2491-2550 at 9.0.8). library: Footprint library nickname (e.g. "Resistor_SMD"), or a path to a .pretty directory. A nickname is resolved as update_pcb_from_schematic resolves it: the project's fp-lib-table beside the board, .pretty directories beside the board, KICAD_FP_LIB, the user's global fp-lib-table (with the libraries the Plugin and Content Manager installed), then KiCad's stock footprints. Optional; omit for a pad-less marker. footprint: Footprint name within that library (e.g. "R_0805_2012Metric"). Required when library is given. pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.

Remove a component by reference designator. Args: reference: Reference designator to remove (e.g. "U2") schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

Detect and remove trace segments with unconnected endpoints. Iteratively removes dangling segments until no more are found. A segment is considered dangling if either endpoint does not connect to a pad, via, or another trace endpoint. Args: pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.

Remove a footprint by reference designator. Args: reference: Reference designator (e.g. "R1") pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.

Remove a hierarchical label by name or UUID. Args: text: Label text to match schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default. uuid: Optional UUID for disambiguation when multiple labels share a name

Remove a hierarchical sheet block from a parent schematic. Identify the sheet by name, uuid, or both. If name matches multiple sheets, returns an error with UUIDs for disambiguation. Args: parent_schematic_path: Path to parent .kicad_sch name: Sheet name to match uuid: Sheet UUID for unambiguous identification delete_child_file: If True, delete the child .kicad_sch file (unless still referenced by another sheet)

Remove a junction at the given coordinates. Args: x: X position y: Y position schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

Remove net label(s) or global label(s) by text, optionally filtered by position. If x and y are provided, only removes labels matching both text AND position (within 0.1mm tolerance). Otherwise removes ALL labels with matching text. To move a global label, remove it and re-add with add_global_label (which takes shape and rotation). Args: text: Label text to match (e.g. "VCC", "PGND") x: Optional X position filter y: Optional Y position filter schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

Remove no-connect flag(s) from a component pin. Removes every no-connect at the pin's position, so stacked duplicates from repeated no_connect_pin calls clear in one go. Args: reference: Component reference (e.g. "U2") pin_name: Pin name (e.g. "NC") or number (e.g. "3") schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

Remove a pin from a hierarchical sheet block. Args: sheet_uuid: UUID of the sheet pin_name: Name of the pin to remove schematic_path: Path to parent .kicad_sch. Optional; omit to use the configured default.

Remove text annotation(s) by content, optionally filtered by position. If x and y are provided, only removes texts matching both content AND position (within 0.1mm tolerance). Otherwise removes ALL texts with matching content. Args: text: Text content to match x: Optional X position filter y: Optional Y position filter schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

Remove trace segments matching the given filters. Does not remove vias. At least one filter (net_name, layer, or bounding box) is required. Args: net_name: Filter by net name layer: Filter by layer name (e.g. "F.Cu", "B.Cu") x_min: Left edge of bounding box filter (mm) y_min: Top edge of bounding box filter (mm) x_max: Right edge of bounding box filter (mm) y_max: Bottom edge of bounding box filter (mm) pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.

Remove a wire segment by its endpoint coordinates. Matches wires with endpoints within 0.1mm tolerance (in either order). Use list_schematic_wires to get wire coordinates first. Args: x1: Start X y1: Start Y x2: End X y2: End Y schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

Reorder hierarchical sheets by specifying the desired UUID order. Args: page_order: List of sheet UUIDs in desired order schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.

Run Design Rules Check (DRC) on a PCB. Returns structured report with violations. Args: pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default. output_dir: Directory for report file (default: same as PCB). Optional; omit to use the configured default.

Run Electrical Rules Check (ERC) on a schematic. Auto-redirects to root schematic for sub-sheets to avoid false positives from missing hierarchical context. Returns JSON report with violations. Args: schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default. output_dir: Directory for report file (default: same as schematic). Optional; omit to use the configured default. project_path: Path to .kicad_pro file for explicit root resolution

Run a KiCad jobset file. Args: jobset_path: Path to .kicad_jobset file

Set any property on a placed component, or rename it. Creates the property if it is missing. Reference, Value and Footprint are mirrored into the symbol's own instances and into the root symbol_instances table, so setting key="Reference" is how a component is renamed and both views stay in step. The root table needs the .kicad_pro to resolve the hierarchy path; a loose .kicad_sch with no project beside it keeps the symbol correct and leaves that table alone. Args: reference: Component reference (e.g. "R1") key: Property name (e.g. "MPN", "Tolerance", "Value") value: Property value schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

Create or update a net class with design rules and assign nets. Edits the KiCad project file (.kicad_pro) alongside the board to define the net class and assign nets. Does NOT require pcbnew. Args: name: Net class name (e.g. "Power", "HighSpeed") nets: List of net names to assign to this class track_width: Track width in mm (None = use default) clearance: Clearance in mm (None = use default) via_size: Via diameter in mm (None = use default) via_drill: Via drill in mm (None = use default) pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.