# kicad-kbplacer: placing and routing mechanical keyboard switches in KiCad

> kbplacer is a KiCad plugin and Python package that places switch and diode footprints on a keyboard PCB from a layout description such as KLE, VIA, QMK or ergogen, then routes the switch matrix tracks. It suits a keyboard builder who wants the repetitive placement and routing done for them, and it does not attempt to generate the whole board.

**adamws/kicad-kbplacer** — KiCad plugin for automatic keyboard's key placement and routing

- Repository: https://github.com/adamws/kicad-kbplacer
- Stars: 543 · Forks: 37
- Language: Python
- License: GPL-3.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/adamws-kicad-kbplacer

## The tedium it removes, and the scope it keeps

kbplacer is a KiCad plugin for mechanical keyboard design that features automatic key placement and routing based on layout descriptions from Keyboard Layout Editor NG and from ergogen.

The motivation section gives the reasoning plainly. All PCBs for mechanical keyboards share common properties, which creates great opportunity for scripting. The project does not aim to provide a complete automatic PCB generation tool, and what it does is speed up the development process by reducing tedious element placement and routing tasks.

That boundary is the right one to hold on to when evaluating it, because a keyboard PCB has a small number of genuinely variable decisions, the case shape, the mounting style, the plate, the port position and the connector, and a large number of identical ones, dozens of switches in a grid, a diode next to each one, and a matrix of tracks connecting them. The interesting engineering work is in the variable decisions, and the repetitive work is exactly what a script is good at.

The feature list follows the same split: automatic keys and diodes placement, track routing and track template replication, support for KLE, VIA, QMK and ergogen inputs, user selectable diode position in relation to key position, configurable additional elements placement, and board outline generation.

The project is Python, GPL-3.0 licensed, and the pyproject.toml classifies it as Development Status 5 - Production/Stable with Intended Audience Manufacturing. The latest releases are v0.17 from 2026-06-05, v0.18 from 2026-06-10 and v0.19 from 2026-08-08, and the last push to the repository was on 2026-10-22.

The topics list the domain precisely: action-plugin, keyboard, kicad, kicad-plugin, mechanical-keyboard and pcbnew.

## Two ways to install, and the pcbnew dependency that shapes both

There are two installation routes, and they serve different purposes.

As a KiCad plugin, you use KiCad's Plugin and Content Manager and select Keyboard footprints placer from the official plugin repository. For the development version there is a custom plugin repository, automatically updated with the latest master branch builds. For development work itself the readme recommends checking out the repository and copying, or linking, the content of the kbplacer directory into one of KiCad's plugin search paths, with a pointer to KiCad's own pcbnew API guide. After installation the plugin starts from its toolbar icon or from the Tools then External Plugins menu.

As a Python package, it installs with pip:

```shell
pip install kbplacer
```

But there is a catch stated in capitals. When installed this way it cannot be launched from KiCad as a KiCad plugin. That option exists for usage via a command line interface or for integrating with other tools. The readme says the CLI provides more options but is generally recommended for more advanced users, for example it allows creating PCBs without a schematic, which is a non-typical KiCad workflow.

The important note is about pcbnew. Most of the kbplacer package's functionality depends on the pcbnew package, which is distributed as part of the KiCad installation. On Windows this means it is required to use the Python bundled with KiCad. On Linux the pcbnew package should be available globally, which the readme says can be verified by running:

```shell
python -c "import pcbnew; print(pcbnew.Version())"
```

so it may not work inside an isolated environment. To install inside a virtual environment created with venv, it is required to use the --system-site-package option when creating the environment.

That last sentence is the kind of detail that costs an afternoon if you hit it cold. The reason is structural: kbplacer is a KiCad plugin first, and it manipulates the pcbnew Python API, which lives inside KiCad's own interpreter. A KiCad plugin cannot use your project virtualenv, and a Python package that needs pcbnew cannot use a virtualenv that hides it. Both installation methods can be used simultaneously, and when installed as a KiCad plugin some scripting capabilities are still available, but using kbplacer in another Python script requires the package install.

## The traditional workflow, and what the plugin expects from you

Using the tool from KiCad is described as the traditional way of using it. Before it can be used on a kicad_pcb project file, the user needs to create it and populate it with footprints, and in a typical KiCad workflow this starts by creating a schematic. When the PCB file is ready, you start the kbplacer plugin in GUI mode from KiCad and run it with the selected options.

The expectation on the schematic is specific, and it is a switch matrix schematic meeting stated requirements. Each switch has a connected diode. Diodes can be connected in either direction, and the track router attempts to connect the closest pads of a switch and a diode as long as both have the same netname, that is, are connected on the schematic. So the plugin is not inferring your matrix topology, it is reading the netlist you drew and routing it.

That is the correct division of labour. The schematic expresses the electrical design, the layout file expresses the physical arrangement, and the plugin does the mechanical work of placing the parts and routing the matrix.

Beyond the main placement there is a set of secondary features that are where a real keyboard build actually gets fiddly. Diodes can be placed on either side of a switch relative to each other, and there is automatic diode orientation adjustment. Track templating replicates a track pattern rather than routing every route from scratch, which is how you get the parallel rows of a matrix to look right. Additional elements can be placed, and the board outline can be generated.

There is also a run-without-layout mode, and the CLI entry point is registered in the package manifest as kbplacer = "kbplacer.__main__:app", so the tool is usable as a command as well as a plugin.

## Four input formats, one experimental

The input format support is what makes the tool fit into an existing keyboard design workflow rather than imposing one.

Four formats are supported: KLE, VIA, QMK and ergogen. They cover different parts of the ecosystem. KLE is the original layout description format, established by ijprest and used by the classic Keyboard Layout Editor; the readme notes that the Keyboard Layout Editor NG referenced throughout the documentation is a modernized re-implementation using the same data format. VIA is the VIA firmware layout format, QMK is the QMK keyboard info JSON layout format, and 

The difference between them matters practically. KLE and VIA describe a key grid. QMK describes a keyboard's physical layout and keymap metadata. Supporting all four means kbplacer can consume the output of the tool a designer already uses rather than requiring a conversion step into a format kbplacer happens to prefer.

The warning is explicit, though. Ergogen support is a new experimental feature and it has not been tested extensively. That is worth taking at face value: an untested integration between two independently evolving tools is exactly where a keyboard builder will lose an evening to a misplaced diode.

The repository ships examples to work from, in an examples/ directory, and the demo/ directory holds a complete project including demo.kicad_pcb, demo.kicad_sch, demo.kicad_pro and demo.kicad_prl files along with several KLE JSON inputs such as kle.json, kle-internal.json and kle-column-staggered.json and the explicitly annotated variant. A demo project is the fastest way to see what the tool expects on the schematic side.

## Where kbplacer is the wrong choice

The first limitation is the scope, and the project states it before you discover it. This is not a complete automatic PCB generation tool. If you want a keyboard board produced end to end, with the case, the plate, the mounting holes, the USB port and the controller footprint all derived from one description, kbplacer is not that tool and you should look at ergogen for the configuration side and use a PCB tool for the board.

The second is that you still do the schematic. The plugin reads a switch matrix you have drawn, with a diode on every switch and consistent netnames, and routes it. It does not derive the matrix for you, and it does not check your matrix design. The switch matrix, the row and column wiring and the diode orientation are still yours to get right, and the plugin's routing will faithfully follow whatever you drew, including a mistake.

The third is the pcbnew coupling, which is the deepest constraint in the project. Everything depends on the pcbnew Python API from a specific KiCad installation, which means the version of KiCad you have and the version of Python it ships with determine what works. On Windows you are pinned to KiCad's bundled interpreter, on Linux a virtualenv that hides the system pcbnew breaks the tool, and a plugin that runs inside KiCad cannot see your project's dependencies. Any project with a Python environment, a dependency manager and a CI pipeline has to accommodate that rather than work around it.

The fourth is that the ergogen path is experimental, as the readme warns. If your workflow starts from an ergogen description, you are on the least-tested path of the four, and the failure modes are likely to be geometric rather than crashing, which is harder to diagnose.

The fifth is that the tool does not manufacture anything. It places footprints and routes tracks in a board file. The board still has to be sent to a fabricator, and the mechanical design, the plate, the stabiliser positions and the case are all still outside its scope, so the time it saves is real but it is a fraction of the time a keyboard build takes.

## Conclusion

kbplacer fits a keyboard designer with a layout file and a schematic whose switch matrix is already drawn, since the plugin takes the KLE, VIA, QMK or ergogen description and does the repetitive placement and track routing, and since it can also run without a schematic from the command line. It is the wrong choice if you want a full board generator, because the readme says it does not aim to provide a complete automatic PCB generation tool, and it is the wrong choice if you need the ergogen path to be reliable, since the readme labels that support a new experimental feature. Before installing it, note that the pcbnew module comes from your KiCad installation, so on Windows you must use the Python bundled with KiCad, and that the last push was on 2026-10-22 with v0.19 released on 2026-08-08 under a GPL-3.0 licence.

## FAQ

### How do I install kicad-kbplacer as a KiCad plugin?

Use KiCad's Plugin and Content Manager and select Keyboard footprints placer from the official plugin repository. For development versions there is a custom plugin repository updated from the master branch, and for local development you can copy or link the kbplacer directory into one of KiCad's plugin search paths.

### Can I install kbplacer with pip?

Yes, run pip install kbplacer. But installed that way it cannot be launched from KiCad as a plugin; the install exists for command line use and for integration with other tools. Most of its functionality depends on the pcbnew module from your KiCad installation, so on Windows you must use the Python bundled with KiCad.

### Which keyboard layout formats does kicad-kbplacer accept?

KLE, VIA, QMK and ergogen. KLE is the original layout description format used by Keyboard Layout Editor, and the Keyboard Layout Editor NG referenced in the documentation is a modernized re-implementation of the same format. Ergogen support is described as a new experimental feature that has not been tested extensively.

### What does kicad-kbplacer do once installed?

It places switch and diode footprints according to the layout description, routes the switch matrix tracks, replicates track templates, places additional elements and can generate the board outline. It expects a schematic with a switch matrix in which each switch has a connected diode and matching netnames.

### What licence is kicad-kbplacer released under?

GPL-3.0, with the same identifier declared in the package metadata as the GNU General Public License v3. The last push to the repository was on 2026-10-22 and the newest release is v0.19 from 2026-08-08.

## Sources

- [adamws/kicad-kbplacer on GitHub](https://github.com/adamws/kicad-kbplacer)
- [Issues](https://github.com/adamws/kicad-kbplacer/issues)
- [License: GPL-3.0](https://github.com/adamws/kicad-kbplacer/blob/master/LICENSE)
- [README](https://github.com/adamws/kicad-kbplacer/blob/master/README.md)
- [Releases](https://github.com/adamws/kicad-kbplacer/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/adamws-kicad-kbplacer