Skip to main content

Toolchain Setup

This guide will show you how to set up a development environment for building ZMK locally.

Install Dependencies

Click the operating system you are using. (The VS Code & Docker option can be used on any OS.)

Open Zephyr's Getting Started Guide and follow the instructions under these sections:

Return to this guide once you are finished with each section.

Install West

west is the Zephyr® Project's meta-tool used to configure and build Zephyr OS applications.

West can be installed by using the pip python package manager. The Zephyr™ instructions are summarized here:

Install west:

pip3 install --user -U west

Verify that west is installed:

west --version

This should print a message like "West version: v0.14.0". If it prints an error instead, make sure ~/.local/bin is on your PATH environment variable. You can add it with these commands:

echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc

Get Source Code

Next, you'll need to clone the ZMK source repository if you haven't already. Navigate to the folder you would like to place your zmk directory in and run the following command:

git clone https://github.com/zmkfirmware/zmk.git

Initialize & Update Zephyr Workspace

Since ZMK is built as a Zephyr™ application, the next step is to use west to initialize and update your workspace. The ZMK Zephyr™ application is in the app/ source directory:

Step into the repository

cd zmk

Initialize the Application

west init -l app/

Update to Fetch Modules

west update
tip

This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!

info

If you're using Docker, you're done with setup! You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code.

Once your container is restarted, proceed to Building and Flashing.

Export Zephyr CMake package

This allows CMake to load the code needed to build ZMK.

west zephyr-export

Install Zephyr Python Dependencies

Some additional Python dependencies are listed in Zephyr's scripts/requirements.txt file.

pip3 install --user -r zephyr/scripts/requirements.txt