Love mechanical keyboards? You're among friends. Friends who want to show you how to use QMK with the great RP2040 microcontroller from Raspberry Pi. Support for this was added in July 2022 to the develop branch by the QMK community.

If you don't care to set up your computer to compile QMK, each example also includes a .uf2 file that you can download and immediately start using on a compatible RP2040 board, no software installation required.

Install QMK on your computer

Each kind of operating system has different steps for this, and if you run into trouble check the official instructions from qmk for more information and troubleshooting info!

Windows-based systems

For Windows, the best practice is to install "QMK WSL" following the official instructions. If you prefer, you can install the older "QMK MSYS" instead, but in general QMK WSL is faster and more reliable for compiling QMK code.

Heading 3 Delete Cancel Save

Debian-based systems including Ubuntu

For Debian-based Linux distributions (including Ubuntu and Raspberry Pi OS), install git and pip using the package manager and then install the qmk command:

sudo apt install -y git python3-pip
python3 -mpip install --user qmk

For macOS systems

For macOS, you will need to install Homebrew. Follow the instructions on Then, install the qmk command using brew:

brew install qmk/qmk/qmk

Finish setting up the qmk environment

Check that the qmk command is working for you by asking it to report its version:

$ qmk --version

Next, for any kind of system, run

qmk setup

Answer "y" when asked to clone the firmware and install dependencies. Depending on your system, this may also prompt you for your password to install additional operating system packages.

Once this is done, you will have the qmk command available, and an up to date copy of the source code in qmk_firmware folder within your home folder. The following pages of this guide show how to build and install a firmware.

Switching back to CircuitPython or Arduino

Your RP2040 is fully reprogrammable through the RPI-RP2 bootloader, but automatic reset to upload from the Arduino environment does not work when the board has a QMK firmware installed. Instead, you need to manually access the bootloader. For more details on how to access the bootloader, check the guide for your particular board. Here are some general instructions:

  • If a RESET button is available, double click it. This works only when the firmware is correctly functioning. If it doesn't work, use one of the below methods.
  • If a RESET button is available, hold down the BOOT button and click RESET once.
  • Hold down the BOOT button while plugging in the device

Once your computer has recognized the RPI-RP2 bootloader, you can either drag a new UF2 to the drive (CircuitPython, QMK, or Arduino) or initiate the build and upload of a firmware (Arduino or qmk flash)


Ready to get down to business? Pick up some compatible hardware, then continue to one of the other pages in this guide to flash the QMK firmware to your RP2040 board, and learn more about how to modify and customize QMK along the way. If you don't feel like compiling software right now, we've also provided a .uf2 file for each example so you can load it on your board right away.

Angled shot of MacroPad
Strap yourself in, we're launching in T-minus 10 seconds...Destination? A new Class M planet called MACROPAD! M here, stands for Microcontroller because this 3x4 keyboard...
Angled shot of short black microcontroller.
A wild Kee Boar appears! It’s a shiny KB2040! An Arduino Pro Micro-shaped board for Keebs with RP2040. (#keeblife 4 evah) A lot of folks like using Adafruit...
Angle shot of Raspberry Pi Pico RP2040
The Raspberry Pi foundation changed single-board computing when they released the Raspberry Pi computer, now they're ready to...
angled shot of 20 6mm mini tactile button switches.
Little clicky switches are standard input "buttons" on electronic projects. These work best in a PCB but
Angled shot of half-size solderless breadboard with red and black power lines.
This is a cute, half-size breadboard with 400 tie points, good for small projects. It's 3.25" x 2.2" / 8.3cm x 5.5cm with a standard double-strip in the...
Monochrome OLED module wired to Feather showing text and circles
These displays are small, only about 1" diagonal, but very readable due to the high contrast of an OLED display. This display is made of 128x32 individual white OLED pixels, each...
Angled of of JST SH 4-Pin Cable.
This 4-wire cable is 50mm / 1.9" long and fitted with JST SH female 4-pin connectors on both ends. Compared with the chunkier JST PH these are 1mm pitch instead of 2mm, but...

This guide was first published on Jul 26, 2022. It was last updated on Jul 26, 2022.

This page (Overview) was last updated on Jul 06, 2022.

Text editor powered by tinymce.