keymap-drawer for Parsing and Drawing QMK and ZMK Keymaps

Why keymap-drawer Exists

Keyboard firmware keymaps are not always easy to inspect visually. A QMK or ZMK file may describe several layers, conditional actions, hold-taps, and combos across a compact board. keymap-drawer addresses that specific problem by parsing an existing firmware keymap into a human-editable YAML representation and then drawing that representation as SVG.

The target audience is keyboard firmware users working with QMK or ZMK, particularly people using smaller keyboards where hold-taps and combos are common. It is also relevant to maintainers who want a diagram that separates physical key positions from the actions assigned to them. The project does not replace the firmware build. It produces a reviewable representation and a drawing artifact.

The README describes a web application based on Streamlit, a command-line tool, and a Python package. That range matters because the same underlying functionality is available for quick browser use and for scripted workflows. The tool is intentionally more programmatic than a visual layout editor. A user can start from an existing keymap, adjust the generated YAML, and render the result again.

The YAML, Parser, and SVG Pipeline

The central design is a separation between the physical keyboard layout and the logical keymap. The physical side describes where keys are located, including rotated keys and parametrized ortholinear layouts. The keymap side describes layers, key actions, hold-taps, and combos. This separation lets one physical layout remain stable while firmware mappings change.

The `keymap parse` command creates the YAML representation used by the drawing command. QMK parsing accepts JSON-format keymaps, while ZMK parsing accepts `.keymap` files. For ZMK, the parser preprocesses input in a way similar to the ZMK build system, expanding `#define` and `#include` directives. The generated YAML is not just a raw transcription. It is intended to be edited, so legends such as firmware identifiers can be replaced with shorter display labels and key types can be adjusted.

The drawing stage outputs SVG. Combos receive special visual treatment. Adjacent combos can be represented directly, while non-adjacent or three-key-plus combos can specify `align` and `offset`. The renderer draws dendrons from the combo to its keys. If a particular geometry does not work well, the README also documents an alternative of producing a separate diagram for each combo. Custom SVG glyphs can be used alongside Unicode text.

Configuration files can customize both parsing and drawing. The repository includes `CONFIGURATION.md`, `KEYMAP_SPEC.md`, and `PHYSICAL_LAYOUTS.md`, which are the relevant references for understanding accepted properties and physical layout definitions.

Installing keymap-drawer and Creating YAML

The README recommends `pipx` because it installs the command in an isolated environment. This is the documented installation path for a normal command-line user.

pipx install keymap-drawer

After installation, the package exposes the `keymap` command:

keymap --help

The alternative documented by the project is installation into a virtual environment with `pip`, or into the user install directory. The package metadata requires Python `>=3.12,<4.0`, so an older Python installation is outside the declared support range. The `pyproject.toml` entry point maps `keymap` to `keymap_drawer.__main__:main`.

A first real use starts with an existing QMK keymap. QMK input must be JSON. The README gives the following command for a keyboard called `ferris`, using the keymap directory layout associated with that example:

qmk c2json ~/qmk_firmware/keyboards/ferris/keymaps/username/keymap.c | keymap parse -c 10 -q - >sweep_keymap.yaml

The `-c` option supplies the total number of columns, while `-q` selects quiet output and `-` reads from the piped JSON stream. The output is redirected to `sweep_keymap.yaml`. A user should check that the YAML was created and then inspect it before drawing.

For ZMK, the documented command takes a `.keymap` file directly:

keymap parse -c 10 -z ~/zmk-config/config/cradio.keymap >sweep_keymap.yaml

The `-z` option selects ZMK parsing. According to the README, ZMK parsing can currently determine combos, hold-taps, mod-morphs, sticky keys, and layer names. For layer names, `display-name` takes precedence over the layer node name.

QMK and ZMK Parsing Boundaries

QMK support has a concrete limitation. The parser accepts only JSON-format QMK keymaps, not arbitrary `keymap.c` source directly. The README documents a conversion path using `qmk c2json`, and also mentions `qmk via2json` for converting a VIA backup. This means a QMK user may need an extra conversion command before parsing.

There is a second limitation in the `keymap.json` format itself. The README states that combos and `#define`d layer names will not appear in the parsing output. Layer names can be supplied manually through the layer names parameter, but combo definitions require a separate manual step. The documented workflow therefore expects a QMK user to add combo definitions using key position indices after parsing.

The project is not a fully interactive visual editor. Its editable format is YAML, and its output is SVG. This makes it suitable for reviewing a keymap, changing display labels, documenting a design, or producing a diagram in a build pipeline. It is less suitable if the main requirement is dragging keys around in a graphical editor or generating a keymap from an interactive layout without writing or editing structured data.

The parsed output is a starting point. The README specifically advises changing display forms, adding `align` and `offset` for difficult combo placement, and modifying `type` values such as `ghost` for optional keys. These edits show why the parser is not presented as a complete replacement for firmware configuration.

Customization, Icons, and Automation

Customization is available at both stages. A config file can alter parser behavior, including how parsed keys are displayed, and can also affect drawing. This is useful when the raw firmware action names are too verbose for a diagram. The README gives `&bootloader` as an example that can be changed to `BOOT` for display.

The SVG output supports arbitrary custom SVG icons in addition to Unicode text. That is a meaningful difference from a basic text-only renderer, especially for keyboards that use symbols or firmware actions without a convenient short text legend. The exact icon format and configuration details are documented in the repository's `CONFIGURATION.md`.

The project also documents an automated drawing workflow. The repository contains a `site` directory and development dependencies including `mypy`, `pylint`, `black`, and `python-lsp-server`. These details indicate a Python package with separate application and development concerns, although the README excerpt does not specify every automation command. The safe operational conclusion is limited: the CLI and Streamlit application are documented, while the complete workflow configuration should be read in the relevant repository files before scripting it.

A practical review cycle is parse, draw, inspect, edit, and draw again. This is particularly important for combos. Their placement depends on the physical layout and on how the selected keys are arranged, so a diagram that is readable for one board may need `align` or `offset` changes on another.

Licensing, Runtime Requirements, and Maintenance

The repository uses the MIT license, and `pyproject.toml` identifies the project as `keymap-drawer` version `0.23.0`. The MIT license permits use and modification under its terms, but license obligations and compatibility with a particular distribution remain separate questions for the adopting organization.

The declared Python requirement is `>=3.12,<4.0`. The dependency set includes Pydantic, PyYAML, tree-sitter, tree-sitter-devicetree, pyparsing, platformdirs, pydantic-settings, and pcpp. The presence of a C preprocessor package and tree-sitter packages means the project is not simply a static YAML renderer. Its parser depends on handling source and firmware syntax rather than only drawing hand-authored configuration.

The repository is not archived, and the last push was on 2026-08-12. The most recent listed release is v0.23.0, dated 2026-03-17. Those dates describe repository activity, but they do not by themselves guarantee compatibility with a particular QMK or ZMK release. Upgrade planning should account for Python 3.12, parser dependency changes, and any schema changes described in `KEYMAP_SPEC.md`.

On Windows, the README recommends using `-o` or `--output` when saving command output instead of redirecting standard output, because redirected YAML or SVG text may encounter encoding issues. That is a platform-specific operational constraint worth checking before adding the CLI to an automated Windows workflow.

Editorial conclusion

Adopt keymap-drawer when you maintain QMK or ZMK firmware and want editable YAML plus SVG output, especially for small keyboards with layered input. Do not choose it for native keymap.c parsing or for fully interactive layout editing. Check Python 3.12 compatibility, confirm that your firmware format is supported, and inspect the generated SVG before adopting the YAML as a maintained configuration artifact.

Frequently asked questions

Official sources

1. caksoylar/keymap-drawer on GitHub
2. License: MIT
3. Project website
4. README
5. Releases