# QMK Firmware: Building and Flashing Custom Keyboards from Source

> QMK Firmware is a GPL-2.0 C firmware for AVR and ARM keyboards, maintained by Jack Humbert of OLKB with community contributions. It is powerful, configurable, and not something you should install unless you are willing to keep a toolchain in working order.

**qmk/qmk_firmware** — Open-source keyboard firmware for Atmel AVR and Arm USB families

- Repository: https://github.com/qmk/qmk_firmware
- Website: https://qmk.fm
- Stars: 20,734 · Forks: 44,325
- Language: C
- License: GPL-2.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/qmk-qmk-firmware

## The problem QMK Firmware solves: keymaps as source code, not vendor software

Most keyboards ship with a configuration utility that stores your layout in the keyboard's own memory. That works until you want behaviour the utility does not expose: layers that change under your fingers, tap-and-hold distinctions, per-key timing, or one keymap shared across several boards. QMK Firmware takes the other route. Your layout lives in the repository as C source, gets compiled against the specific keyboard definition, and is flashed to the controller.

The README describes the project as a keyboard firmware based on tmk_keyboard with features for Atmel AVR and ARM controllers, naming the OLKB product line, the ErgoDox EZ and the Clueboard product line as the boards it was built around. Those are the maintainers' own products: Jack Humbert handles OLKB, ZSA Technology Labs the ErgoDox EZ, Zach White the Clueboard, and Phil Hagelberg the Atreus. Community support covers many more boards under keyboards/.

The audience is therefore narrow and specific. You are a good fit if you own one of those boards, or a community-supported one, and you are comfortable editing a C keymap file and running a build. You are a poor fit if you want a graphical remapper with no local toolchain, or if your keyboard's firmware is locked and the vendor does not publish a QMK port.

## How the repository is organised: keyboards, quantum, tmk_core and platforms

The top level of the repository separates concerns in a way that matters when you go looking for something. keyboards/ holds per-board definitions. quantum/ holds the shared behaviour that keymaps call into. tmk_core/ is the inherited core from tmk_keyboard. platforms/ and drivers/ hold the controller-specific and hardware-specific code. layouts/ holds shared layout definitions, and users/ holds per-user configuration that sits outside a single keyboard.

Build configuration is not scattered. builddefs/ contains the makefile fragments that the top-level Makefile includes, and paths.mk defines where the build looks for things. The root Makefile is explicit that it must not run in parallel, with a comment saying it could screw things up, while submakes still benefit from -jx. That is a real constraint if you are used to throwing -j at everything.

The Makefile also shows how the build finds your userspace. It queries the qmk binary, first for QMK_USERSPACE in the environment, and falls back to the legacy user.overlay_dir config key. If neither is set, the userspace is simply empty. This is the mechanism behind the users/ directory: your keymap can live in the repository, or in a separate userspace tree that the build overlays. The README does not explain this; the Makefile does.

Dependencies are declared in requirements.txt: argcomplete, colorama, dotty-dict, hid, hjson, jsonschema, milc, pygments, pyserial, pyusb and pillow. There is also a requirements-dev.txt for development work. Those names tell you the CLI is a Python program that talks to hardware over hid and pyserial, which is why a working USB stack and permissions matter more than raw compute.

## Installing QMK Firmware on Linux and building a first keymap

The README points to docs.qmk.fm for setup rather than listing steps itself, so treat the commands below as the shape of the workflow and confirm the details on the docs site for your distribution. The CLI is the qmk binary, and the top-level Makefile calls it to resolve your userspace, so it needs to be on PATH before a build.

Start by cloning the repository and installing the Python requirements into a virtual environment:

```bash
git clone https://github.com/qmk/qmk_firmware.git
cd qmk_firmware
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

With the dependencies in place, the qmk CLI is what you use for setup and compilation. The Makefile expects it to exist and to answer env and config queries:

```bash
qmk setup
qmk config user.overlay_dir
qmk compile -kb planck -km default
```

The middle command is the legacy key the Makefile falls back to when QMK_USERSPACE is not exported; if it prints nothing, your userspace is unset and the build will use only what is in the repository. The compile step produces a firmware file under the build directory named for the keyboard and keymap. To edit behaviour, copy a keymap directory under keyboards/ for your board, change the layout array in its C file, and recompile. Flashing is board-specific and documented per keyboard on docs.qmk.fm; the README gives no flashing command and no recovery procedure if a flash goes wrong.

## Where QMK Firmware becomes the wrong tool

The first limitation is hardware. QMK targets Atmel AVR and ARM USB families, as the repository description states. A keyboard built around a different controller is not a candidate, and the related search traffic for an ESP32 port does not correspond to anything the README claims. If your board is not listed under keyboards/ and nobody has written a port, you are writing one.

The second is the toolchain. Every change runs through Python dependencies, a cross-compiler and a flashing step. That is fine for someone who treats a keyboard as a small software project. It is a poor trade for someone who wants to move two keys once. A graphical remapper that writes to the keyboard's own storage has no build step and no local environment to break.

The third is recovery. The README documents what QMK is, which boards it covers and who maintains it. It does not document rollback, and it does not describe what happens when a flash is interrupted. Because the firmware is compiled per board, the recovery path depends on whether your keyboard exposes a bootloader entry method, which is a per-keyboard question answered on docs.qmk.fm rather than in the repository root. Anyone flashing a board they cannot afford to lose should read that page before the first attempt, not after.

Finally, the Makefile's deliberate refusal to run in parallel at the top level is a small but real cost on large builds, and the QMK_USERSPACE resolution chain means a misconfigured userspace can silently change what gets compiled.

## QMK Firmware versus VIA: compiled keymaps against live remapping

The comparison people actually search for is QMK against VIA, and the difference is architectural rather than cosmetic. VIA-style remapping writes layout changes into the keyboard at runtime, so the keyboard is the source of truth and the host software is a client. QMK keeps the source of truth in the repository: your keymap is a C file, the build produces a firmware image, and the keyboard receives a complete program.

That has consequences in both directions. A compiled keymap can express things a runtime remapper cannot easily represent, because it is ordinary code compiled with the rest of the firmware. It is also reproducible: the same commit and the same keymap produce the same image, which matters if you keep several boards in sync. The cost is that nothing changes until you rebuild and reflash, and you need the toolchain on whichever machine you use.

VIA is the better choice when the keyboard supports it and you want to change a layout on a machine where you cannot install a compiler. QMK is the better choice when the layout is complex enough to deserve version control, or when the board has no runtime remapping support at all. They are not mutually exclusive in principle, but the repository does not document a VIA integration, so do not assume one.

## Maintenance cost, licensing and what the GPL-2.0 means for your keymap

The repository is not archived, and the last push was on 2026-09-10, so the project is being updated. That does not make upgrades free. QMK is a large C codebase with a shared quantum layer, and changes there can affect keymaps that call into it. If you maintain a fork with local modifications, you own the rebase. If you keep your keymap in a separate userspace tree, the overlay mechanism the Makefile resolves through QMK_USERSPACE is what keeps your work out of the way of upstream changes, and that is the arrangement worth using if you plan to track the project over time.

On licensing: the repository carries GPL-2.0 and includes license_GPLv2.md, license_GPLv3.md and license_Modified_BSD.md. The presence of three licence files reflects the mixed provenance of a project built on tmk_keyboard with contributions from many authors, and different parts of the tree may fall under different terms. This is not legal advice. If you intend to ship a commercial keyboard that embeds QMK, or to redistribute a modified firmware, read the licence files in the repository and get your own advice on which terms apply to the files you actually use.

## Conclusion

Adopt QMK if you own a supported board such as a Planck, Preonic, ErgoDox EZ, Clueboard, Cluepad or Atreus, or a community-supported keyboard, and you want keymaps stored as text you can diff and rebuild. Do not adopt it if you only want to remap keys occasionally and would rather not maintain a Python environment and an ARM or AVR toolchain. Before committing, verify that your exact keyboard appears under keyboards/ in the repository, check which controller family it uses, and read the matching page on docs.qmk.fm for the flashing procedure, because the README itself documents no flashing steps and no rollback path.

## FAQ

### What is QMK Firmware?

It is an open-source keyboard firmware based on tmk_keyboard, written mainly in C and aimed at Atmel AVR and ARM USB controllers. The README names the OLKB product line, the ErgoDox EZ and the Clueboard product line among the boards it was built around, with community support for many others.

### How do I install QMK Firmware?

The README directs you to docs.qmk.fm for setup rather than listing steps. The repository ships requirements.txt for the Python CLI, and the top-level Makefile expects a qmk binary on PATH to resolve your userspace before a build.

### How do I use QMK Firmware to build a keymap?

You edit a keymap in C under the keyboard's directory and compile it with the qmk CLI, for example qmk compile -kb planck -km default. The command produces a firmware image named for the keyboard and keymap; flashing is documented per keyboard on docs.qmk.fm.

### Is QMK Firmware safe?

The repository is not archived and the last push was on 2026-09-10, with maintainers named in the README for the main product lines. The README does not document a rollback path if a flash fails, so the risk to weigh is recovery, not provenance.

### Where is the QMK Firmware folder?

The repository layout puts board definitions under keyboards/, shared behaviour under quantum/, the inherited core under tmk_core/, and build configuration under builddefs/ with paths.mk at the root. Your own keymaps can live in users/ or in a separate userspace tree that the Makefile resolves through QMK_USERSPACE.

### Should I use QMK Firmware or VIA?

VIA-style remapping changes the layout on the keyboard at runtime, while QMK compiles a keymap into a firmware image that you flash. QMK suits complex layouts you want under version control; VIA suits quick changes on a machine where you cannot install a toolchain.

## Sources

- [Issues](https://github.com/qmk/qmk_firmware/issues)
- [License: GPL-2.0](https://github.com/qmk/qmk_firmware/blob/master/LICENSE)
- [Project website](https://qmk.fm)
- [qmk/qmk_firmware on GitHub](https://github.com/qmk/qmk_firmware)
- [README](https://github.com/qmk/qmk_firmware/blob/master/README.md)

---

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