Skip to main content

boardwright

Generate and edit KiCad boards and schematics from a short Python description, checked by KiCad itself.

Status: alpha. It makes real, routed, DRC-clean KiCad 10 projects and edits existing ones in place. None of the example boards has been fabricated. The command line is the stable surface; the Python modules will move.

pip install boardwright             # add [live] to edit the board open in KiCad
boardwright doctor                  # what this machine has for each step

Needs KiCad 10 (its libraries and kicad-cli) and Freerouting for autorouting. boardwright doctor finds them in the usual install places, Flatpak included, and names the setting to use when it cannot.

RP2040 board generated by boardwright

What it does

A board is a directory with a board.py: the circuit, where the parts go, and what matters about the layout.

from boardwright.circuit import Circuit

NAME, W, H = "ldo_breakout", 30, 20
CIRCUIT = c = Circuit("LDO breakout")
c.add("J1", "Connector_Generic:Conn_01x02", "VIN", "Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical", {1: "VIN", 2: "GND"})
c.add("U1", "Regulator_Linear:AMS1117-3.3", "AMS1117-3.3", "Package_TO_SOT_SMD:SOT-223-3_TabPin2", {1: "GND", 2: "+3V3", 3: "VIN"})
c.add("C1", "Device:C", "10u", "Capacitor_SMD:C_0805_2012Metric", {1: "VIN", 2: "GND"})
# ...
PLACE = {"J1": (3, 8.7, 0), "C1": (8.5, 10, 90), "U1": (15, 10, 270)}
REVIEW = {"near": [("C1.1", "U1.3", 6.0)]}      # input capacitor within 6 mm of the input pin
boardwright place examples/boards/ldo_breakout    # placement + ratsnest preview, ~5 s, no KiCad
boardwright gen examples/boards/ldo_breakout      # schematic, board, routing, pours
boardwright check examples/boards/ldo_breakout    # KiCad: ERC, DRC + parity, netlist, gerbers, plots
boardwright verify examples/boards/ldo_breakout   # PASS / NOT DONE

verify passes only when KiCad reports zero ERC and DRC findings at every severity, schematic parity included, KiCad's netlist equals the declared circuit, the fab files exist, and the engineering review is clean.

The review exists because a zero DRC is not a good board. An autorouter will run a signal through a power polygon and leave the halves joined by a thin trace, and KiCad accepts it. REVIEW checks what a reviewer would: decoupler-to-pin distance, routed path lengths and pair matching (vias counted), how far a signal runs with no ground on the adjacent layer, ground vias beside signal vias, pour coverage and whether each pour is still one piece, and current capacity per IPC-2221.

Boards that already exist are edited in place and nothing is regenerated:

boardwright existing MYPROJ info              # layers, nets, pours, preview; any size of board
boardwright existing MYPROJ review            # the same review, against a spec beside the board
boardwright existing MYPROJ apply             # MOVE, RIPUP, ROUTES, TRACKS, VIAS, ZONES from the spec
boardwright existing MYPROJ reroute /SDA      # re-route named nets; every other net stays byte-identical
boardwright existing MYPROJ verify            # review + no DRC finding that is not in the baseline
boardwright sch MYPROJ set R12 Value=4k7      # one block of the schematic replaced, the rest untouched
boardwright live apply edit.py                # the same edits to the board open in KiCad, one undo step

How it decides

  • KiCad is the judge. Nothing is "done" on the tool's own arithmetic. Every generated board goes through kicad-cli, and edits to existing designs are compared against a baseline that KiCad produced. Connectivity before and after an edit is checked with netspec, which this project uses to find KiCad.
  • Placement and hand copper are yours; the rest is routed. Power loops, USB pairs and anything sensitive are drawn in board.py (TRACKS, VIAS, ZONES). Parts can be placed by intent: pad_at(1, ("U1", 24), dy=-1.7) puts a capacitor's pad 1.7 mm from pin 24. Freerouting does the remaining small signals, and a pad-to-pad router finishes what it leaves open.
  • Edits are plain data. An edit to an existing board is an ordered list of operations in the board's own coordinates, checked against the board before it runs, so the same file can be applied to the file on disk or to KiCad's open board.

Examples

examples/boards/ has seven boards made with it; all but the library fixture follow a vendor reference design:

Board Layers What it exercises
ldo_breakout 2 the loop itself
rp2040_min 2 0.4 mm QFN, USB-C, crystal, QSPI flash
tps54202_buck 2 a switching regulator's current loops, hand-routed power
stm32f103_min 2 0.5 mm LQFP-48, bottom-side decoupling, USB pair
esp32c3_min 2 RF module with antenna keep-out, USB on the bottom layer
stm32f103_4l 4 inner ground planes, return-path and via review
customlib_test 2 parts from a library outside KiCad's stock set

examples/existing/ has specs for demo projects that ship with KiCad, for trying the existing-board and schematic commands. docs/devlog/ records what each board broke in the tool and what was changed.

Documentation

  • docs/guide.md: the full workflow, every board.py option, existing boards and schematics, the live KiCad client, and what the tool does badly.
  • docs/devlog/gaps.md: known limits.

Known limits

  • Freerouting is not repeatable on dense boards; the pad-to-pad router does not push other tracks aside, tune lengths or route pairs as pairs.
  • Schematic editing changes fields, removes parts, and adds a part by copying one with the same symbol. It cannot add a symbol the sheet does not already use, and a schematic change is pushed to the board in KiCad.
  • Generated schematics are one flat sheet.
  • Impedance figures are closed-form (IPC-2141, about +-10 %); confirm with your fab.
  • KiCad 10 only. The live client uses KiCad's IPC API, which is what KiCad 11 builds on.

Development

just setup     # uv sync --all-extras
just check     # ruff
just test      # pytest; the full KiCad pipeline test skips where KiCad is absent

License

Apache-2.0. The example boards are generated from KiCad's libraries, whose licence (CC-BY-SA 4.0 with an exception for designs that use them) places no restriction on the boards.

Metadata

Release files for boardwright 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for boardwright 0.1.0
File Size Uploaded Provenance Actions
boardwright-0.1.0.tar.gz 68.0 kB With provenance Details for boardwright-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for boardwright 0.1.0
File Interpreter ABI Platform Actions
boardwright-0.1.0-py3-none-any.whl Python 3 none any Details for boardwright-0.1.0-py3-none-any.whl

Total release size: 141.8 kB

Release files / boardwright-0.1.0.tar.gz

Download URL boardwright-0.1.0.tar.gz
Size 68.0 kB
Tags Source
SHA-256 checksum
How to use checksums
87eb5dad1d7bd65d50b6e0410737e903773feeb9a2932a07ef2a40f2ce41db26
BLAKE2b-256 checksum
How to use checksums
f4e111aebbab54e363c163556eee400bf76fbacf59caad470e0a866d23caabaa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / boardwright-0.1.0-py3-none-any.whl

Download URL boardwright-0.1.0-py3-none-any.whl
Size 73.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ddff16bdd8f509d48429f3787b8a4d484612c2d1dc373419730284242a186834
BLAKE2b-256 checksum
How to use checksums
dcb75235254768f1531dd77ae35b4a7b22d4208e7c7fb2d89dda81eb6a75f19c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for boardwright 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for boardwright-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page