qmk-layout-fmt

Formatter for QMK keymap.c LAYOUT() blocks.

QMK is an open-source firmware for custom keyboards. Keymaps are defined in C files using LAYOUT() macros that map physical keys to actions across multiple layers.

This tool aligns columns within those layer definitions so that keys line up vertically across rows, making keymaps easier to read and review.

Works with any QMK LAYOUT macro — auto-detects shape from standard names (LAYOUT_split_3x6_3, LAYOUT_ortho_4x12, etc.) and supports custom macros via config file.

Installation

With uv:

uv tool install qmk-layout-fmt

With pipx:

pipx install qmk-layout-fmt

Or directly from the repository:

uv tool install git+https://github.com/OneDeadKey/qmk-layout-fmt

Development

git clone https://github.com/OneDeadKey/qmk-layout-fmt.git
cd qmk-layout-fmt
uv sync
uv run qmk-layout-fmt keymap.c

Maintainer tasks

Requires just:

just build          # build the package
just publish        # build + publish to PyPI
just bump 0.2.0     # update version everywhere
just run keymap.c   # run the formatter locally

Usage

# Format in place (default)
qmk-layout-fmt keymap.c

# Check formatting without modifying (exit code 1 if unformatted, useful for CI)
qmk-layout-fmt keymap.c --check

# All layers share the same column widths (default: each layer aligns independently)
qmk-layout-fmt keymap.c --uniform

Layout shape override

For standard QMK macros (LAYOUT_split_3x6_3, LAYOUT_ortho_4x12, LAYOUT_planck_grid, etc.), the shape is auto-detected from the macro name.

For custom macros, use CLI flags:

qmk-layout-fmt keymap.c --main-rows 4 --cols-per-side 6 --thumb-per-side 3

Or create a .qmk-layout-fmt.toml config file in your project (searched upward from the input file):

[layouts.MY_CUSTOM_LAYOUT]
main_rows = 4
cols_per_side = 6
thumb_per_side = 3

Supported layouts