Compiling QMK Firmware Using Github Codespaces

Compiling QMK Firmware Using Github Codespaces

One of the most common things I'm asked is how one can compile QMK firmware. Up until a few weeks ago my answer would have been that you need to set it up locally on your machine. However, that is not the case anymore since @regicidal.plutophage on my Discord server pointed out a more convenient way using Github Codespaces. 

Codespaces are basically a remote machine running VSCode where you can execute commands and write code all from your browser. Because it's web-based, this will work on any operating system. The only limit I've encountered is that you can't flash firmware from the browser, you need to download and do it from your computer or QMK Toolbox. This isn't a massive issue but can be annoying if you're rapidly trying to develop a board and have to keep compiling, downloading, flashing, and repeating.

In this short guide, you should be able to find out everything you need to start compiling QMK using Github Codespaces. I will also have a video coming out on my channel soon showing this process.

Step 1: Setting Up the Repository

First you're going to want to go to Github and create a free account if you don't already have one. After that, navigate to the qmk_firmware repository and make a clone on your account using the "Fork" button.

Step 2: Creating the Codespace

After your fork is created, you can then create the Codespace by clicking the green "Code" button, navigating to the "Codespaces" tab, and clicking the big green button to create the Codespace.

Create Codespace button

Step 3: Configuring the Codespace

By default, QMK has VSCode set up to hide firmware files as to not clutter up the workspace. You are going to have to remove these exclusions so the firmware files are visible and able to be downloaded after compiling. Click the gear icon in the bottom left and open the settings menu. Then navigate to the "Workspaces" tab and select "Text Editor -> Files" on the left navigation column. Finally click the x next to .hex, .bin, and .uf2 in order to make them visible after compiling.

Step 4: Setup and Test QMK

Everything should be ready now to test but first we have to actually set QMK up. Luckily you can test and set up the Codespace to compile with just a single command. Optionally, you can replace scottokeebs/scotto34:default with the board you want to compile such as folder:keymap.
./util/ scottokeebs/scotto34:default
This will install the required dependencies for QMK along with compiling the firmware for the keyboard and keymap you input. The first time you run this command it may take a while but after everything is configured, only the firmware compilation will need to run and should be relatively quick. 

Step 5: Download and Flash

Once the command completes, you should see a firmware file on the left sidebar. You can download that file by right clicking and the either flash it using your file system or QMK Toolbox depending on the controller you're using.

Where to go from here?

You can now compile QMK meaning you have full access to all the features it offers. It's likely you will just want to modify a keymap for a board you didn't design and if that's the case you can simply press CTRL/CMD + P and search for the board to find it's source code. You may have to do some research to find out what the board folder is called in order to locate it.

However, you might want to create firmware for a board you're developing yourself in which you can run a different command.

./util/ qmk new-keyboard

This will run the command to create a new keyboard in QMK and prompt you with questions to configure it.

Regardless of if you're modifying an existing board or creating your own, inside of the source folder there will be the same files.
  • info.json - This is the file in which you will configure the board. Things such as the matrix, enabling features like displays or RGB, along with various other information about the board.
  • - This file is required and is intentionally left blank. You will add things to this file if told to do so within the documentation.
  • keymaps - This is where you can create different keymaps within folders. The default folder is the default keymap for the board. You can fill out keymap.cs by referencing the QMK keycodes list. You can also create other files here like config.h or to setup certain things only for that keymap.


That's all I have for now and should be enough to get you started. I highly recommend referencing the QMK documentation for more information on any features you want to enable. It would also be a good idea to hop into my Discord server so you can ask questions as you have them.

One last thing to note about Codespaces is that everyone has access to it for 120 hours a month but after that it's not free. It is extremely unlikely that anyone will be using it for more than that per month. You also don't have to worry about wasting your hours as Github will automatically pause the Codespace after inactivity. You can read more about this here.

Good luck and have fun compiling QMK!
Back to blog

Leave a comment