This page describes how to setup and use the QMK CLI.
The QMK CLI makes building and working with QMK keyboards easier. We have provided a number of commands to simplify and streamline tasks such as obtaining and compiling the QMK firmware, creating keymaps, and more.
The CLI requires Python 3.5 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in requirements.txt
.
QMK provides an installable CLI that can be used to setup your QMK build environment, work with QMK, and which makes working with multiple copies of qmk_firmware
easier. We recommend installing and updating this periodically.
If you have installed Homebrew you can tap and install QMK:
brew tap qmk/qmk
brew install qmk
export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
If your system is not listed above you can install QMK manually. First ensure that you have python 3.5 (or later) installed and have installed pip. Then install QMK with this command:
pip3 install qmk
export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
We are looking for people to create and maintain a qmk
package for more operating systems. If you would like to create a package for your OS please follow these guidelines:
QMK_HOME
to have the firmware source checked out somewhere other than ~/qmk_firmware
.If you do not want to use the global CLI there is a local CLI bundled with qmk_firmware
. You can find it in qmk_firmware/bin/qmk
. You can run the qmk
command from any directory and it will always operate on that copy of qmk_firmware
.
Example:
$ ~/qmk_firmware/bin/qmk hello
Ψ Hello, World!
There are some limitations to the local CLI compared to the global CLI:
qmk setup
or qmk clone
qmk_firmware
tree, even if you have multiple repositories cloned.qmk compile
This command allows you to compile firmware from any directory. You can compile JSON exports from https://config.qmk.fm or compile keymaps in the repo.
Usage for Configurator Exports:
qmk compile <configuratorExport.json>
Usage for Keymaps:
qmk compile -kb <keyboard_name> -km <keymap_name>
qmk cformat
This command formats C code using clang-format. Run it with no arguments to format all core code, or pass filenames on the command line to run it on specific files.
Usage:
qmk cformat [file1] [file2] [...] [fileN]
qmk config
This command lets you configure the behavior of QMK. For the full qmk config
documentation see CLI Configuration.
Usage:
qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
qmk doctor
This command examines your environment and alerts you to potential build or flash problems.
Usage:
qmk doctor
qmk new-keymap
This command creates a new keymap based on a keyboard's existing default keymap.
Usage:
qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
qmk pyformat
This command formats python code in qmk_firmware
.
Usage:
qmk pyformat
qmk pytest
This command runs the python test suite. If you make changes to python code you should ensure this runs successfully.
Usage:
qmk pytest