KiCad Monkey

            ▓▓▓▓▓▓▓▓▓▓
          ▓▓▓▓▓▓▓▓▓▓▓▓▓▓
        ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
      ▓▓▓▓░░░░░░▓▓░░░░░░▓▓▓▓
  ░░░░▓▓░░░░░░░░░░░░░░░░░░▓▓░░░░
  ░░░░▓▓░░    ░░░░░░    ░░▓▓░░░░
    ░░▓▓░░  ██░░░░░░  ██░░▓▓░░
      ▓▓░░░░░░░░░░░░░░░░░░▓▓
        ▓▓░░░░░░░░░░░░░░▓▓
          ▓▓▓▓░░░░░░▓▓▓▓
  ░░          ▓▓▓▓▓▓
    ▓▓      ▓▓▓▓▓▓▓▓▓▓
    ▓▓▓▓    ▓▓▓▓▓▓▓▓▓▓
      ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
          ▓▓▓▓░░▓▓░░▓▓▓▓

kicad_monkey is a focused Python package for KiCad source-file parsing, round-trip modeling, close-to-format utilities, and IR-backed 2D rendering.

Use it when you need Python code to inspect or modify KiCad files directly:

• read .kicad_pro, .kicad_sch, .kicad_pcb, .kicad_sym, and .kicad_mod files;
• query schematic and PCB objects through typed model facades;
• compile KiCad-native design netlists and design JSON;
• render schematic, PCB, symbol, and footprint views through plotter IR and SVG;
• make focused model edits, then write KiCad files back out.

This package is the low-level parser/model/rendering library. Larger workflow commands and application orchestration should live in downstream packages.

Install

For library use inside an existing Python environment:

pip install kicad-monkey

For development:

git clone https://github.com/wavenumber-eng/kicad_monkey.git
cd kicad_monkey
uv sync --extra test

Quick Examples

Load A Design And Inspect Nets

from kicad_monkey import KiCadDesign

design = KiCadDesign.from_project_file("hardware/demo.kicad_pro")
netlist = design.to_netlist()

for net in netlist.nets:
    terminals = ", ".join(
        f"{terminal.designator}.{terminal.pin}"
        for terminal in net.terminals
    )
    print(f"{net.name}: {terminals}")

Save the KiCad-native design JSON used by higher-level review tools:

from pathlib import Path

Path("build").mkdir(parents=True, exist_ok=True)
design.save_json("build/design.json")

Render PCB SVG

from pathlib import Path

from kicad_monkey import KiCadDesign

design = KiCadDesign.from_project_file("hardware/demo.kicad_pro")

out_dir = Path("build/svg")
out_dir.mkdir(parents=True, exist_ok=True)

svg = design.to_pcb_svg(
    layers=["Edge.Cuts", "F.Cu", "F.SilkS"],
    profile="enriched",
)
(out_dir / "front-copper.svg").write_text(svg, encoding="utf-8")

Use profile="oracle" when comparing against KiCad CLI output. Use profile="enriched" when an app needs metadata on SVG elements. PCB SVG rendering builds the board render IR before applying layers=, so layer filters reduce output size but do not avoid full PCB parse or IR-build cost.

Render Every Schematic Sheet Instance

Hierarchical designs can instantiate one .kicad_sch file more than once. KiCadSchematicInstance represents each concrete sheet view.

from pathlib import Path

from kicad_monkey import KiCadDesign, render_ir_to_svg

design = KiCadDesign.from_project_file("hardware/demo.kicad_pro")

out_dir = Path("build/schematic-svg")
out_dir.mkdir(parents=True, exist_ok=True)

for sheet in design.schematic_instances():
    doc = design.to_schematic_instance_ir(sheet)
    svg = render_ir_to_svg(doc)
    safe_name = sheet.sheet_name.replace("/", "_").replace("\\", "_")
    (out_dir / f"{sheet.instance_index:02d}_{safe_name}.svg").write_text(
        svg,
        encoding="utf-8",
    )

To find where a reused child schematic appears:

for instance in design.schematic_instances_for("hardware/LED_Controller.kicad_sch"):
    print(instance.sheet_name, instance.sheet_path, instance.sheet_instance_path)

Query And Mutate Schematic Objects

The .objects property is a live read-only query view over model-owned objects. Mutate the returned objects, then call save().

from kicad_monkey import KiCadSchematic

schematic = KiCadSchematic.from_file("hardware/demo.kicad_sch")

for symbol in schematic.objects.where("SchSymbol"):
    if symbol.reference.startswith("R"):
        symbol.set_property_value("Value", "10 kOhm")

for label in schematic.objects.where("SchLabel"):
    if label.effects is not None and label.effects.font is not None:
        label.effects.font.size_x = 1.5
        label.effects.font.size_y = 1.5

schematic.save("hardware/demo.edited.kicad_sch")

Query And Mutate PCB Objects

from kicad_monkey import KiCadPcb

board = KiCadPcb.from_file("hardware/demo.kicad_pcb")

for footprint in board.objects.where("Footprint"):
    reference = footprint.get_property_value("Reference")
    if reference.startswith("U"):
        footprint.set_property_value("Reviewed", "yes", create=True)

for text in board.objects.where("GrText", layer="F.SilkS"):
    text.effects.font.size_x = 1.0
    text.effects.font.size_y = 1.0
    text.text = text.text.strip()

board.save("hardware/demo.edited.kicad_pcb")

Object queries also work with class objects when you prefer typed imports:

from kicad_monkey import Footprint, KiCadPcb

board = KiCadPcb.from_file("hardware/demo.kicad_pcb")
connectors = [
    footprint
    for footprint in board.objects.where(Footprint)
    if footprint.get_property_value("Reference").startswith("J")
]

Scan Large Files Without Full Model Materialization

Use projection or targeted readers when you only need narrow inventories, diagnostics, source spans, or selected object families from a large file.

from kicad_monkey import KiCadPcbProjection

projection = KiCadPcbProjection.from_file("hardware/demo.kicad_pcb")

for model_ref in projection.model_references():
    print(model_ref.reference, model_ref.path)

route_count = len(projection.segments()) + len(projection.vias())
print(f"{route_count} route objects")

For schematic or custom narrow reads, use the generic targeted reader:

from kicad_monkey import SchSymbol, iter_kicad_objects_from_file

for symbol in iter_kicad_objects_from_file("hardware/demo.kicad_sch", SchSymbol):
    print(symbol.reference, symbol.value)

Projection still scans the source file, but it hydrates only the requested object families. Use KiCadPcb, KiCadSchematic, or KiCadDesign when you need mutation, rendering, netlisting, full geometry, or cross-document context. For measured tradeoffs, net-table caveats, and render cost details, see Project Workflows And Read-Path Selection.

Testing

Rack is the primary public gate:

uv run --extra test python tests/rack.py run L0_foundation
uv run --extra test python tests/rack.py run L99_signoff

L99_signoff checks release metadata, changelog coverage, public API contract resolution, API design-doc ownership, Rack test ownership, corpus archive hygiene, and the current ruff/pyright ratchet state.

The redistributable KiCad corpus is restored locally as tests/corpus/kicad.zip; the archive itself is ignored and is not tracked with Git LFS. CI restores that archive from the public object URL recorded in tests/corpus/kicad.archive.toml and verifies size and SHA-256 before tests run. KICAD_MONKEY_CORPUS_URL may override the manifest URL for local testing or an emergency reroute. The loose mirror is ignored locally; test helpers extract the archive on demand when no external corpus is configured.

API Shape

Stable package-root exports are recorded in kicad_monkey.kicad_api_contract. Those names are the public API that downstream code should rely on. The broader package __all__ remains a discovery surface while downstream integrations prove which additional symbols should become stable public exports.

The public OOP facade groups and supporting public classes are documented under docs/design/api. Use Project Workflows And Read-Path Selection for practical guidance on which API to choose for project, render, inventory, and large-file workflows. L99 fails when a stable public class or major interface is missing design documentation or Rack test ownership.

Typical entrypoints:

from kicad_monkey import KiCadDesign, KiCadFootprint, KiCadPcb, KiCadSchematic
from kicad_monkey import KiCadSymbolLib

schematic = KiCadSchematic.from_file("design.kicad_sch")
board = KiCadPcb.from_file("board.kicad_pcb")
design = KiCadDesign.from_project_file("project.kicad_pro")
symbols = KiCadSymbolLib.from_file("library.kicad_sym")
footprint = KiCadFootprint.from_file("package.kicad_mod")

For workflow-level API choice, use Project Workflows And Read-Path Selection as the canonical guide.

Fixture Model

Public fixtures should be redistributable and package-local when possible. Broader fixture families should use this shape:

• input/
• reference_output/
• output/

output/ is transient and should stay local or temporary.

Documentation

• User Guides
• Architecture Decision Records
• Design Notes
• Changelog
• Contributing

License

MIT.