Native Setup

1. Install Zephyr Dependencies

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

• Select and Update OS
• Install Dependencies

info

Zephyr's Install Linux Host Dependencies page may be of use for users of Linux distributions which are not based on Ubuntu.

2. Source Code

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

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

Then step into the repository.

cd zmk

3. Get Zephyr and install Python dependencies

note

These steps are very similar to Zephyr's Get Zephyr and install Python dependencies instructions, but specialized for ZMK.

Install within Virtual Environment

Ubuntu

1. Use apt to install Python venv package:

sudo apt install python3-venv

2. Create a new virtual environment and activate it:

python3 -m venv .venv
source .venv/bin/activate

Windows

1. Create a new virtual environment:

python -m venv .venv

2. Activate the virtual environment:

Command Prompt

.venv\Scripts\activate.bat

Powershell

.venv\Scripts\Activate.ps1

Mac OS

1. Create a new virtual environment:

python3 -m venv .venv

2. Activate the virtual environment:

source .venv/bin/activate

Once activated your shell will be prefixed with (.venv). The virtual environment can be deactivated at any time by running deactivate.

note

Remember to activate the virtual environment every time you start working.

4. Install west:

pip install west

5. Initialize the application and update to fetch modules, including Zephyr:

west init -l app/
west update

tip

This step pulls down quite a bit of tooling, be patient!

6. Export a Zephyr CMake package. This allows CMake to automatically load boilerplate code required for building Zephyr applications.

west zephyr-export

7. Install the additional dependencies found in Zephyr's requirements-base.txt:

pip install -r zephyr/scripts/requirements-base.txt

Install globally

Ubuntu

1. Install west:

pip3 install --user -U west

note

You need ~/.local/bin to be on your PATH environment variable; verify that it is by running

west --version

If this prints an error rather than a west version number, then add ~/.local/bin to your PATH:

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

Windows

1. Install west:

pip install -U west

note

You need the Python scripts directory to be on your PATH environment variable; verify that it is by running

west --version

If this prints an error rather than a west version number, then add said directory to your PATH with PowerShell:

$Scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
$Path = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$Path;$Scripts", 'User')
$env:PATH += ";$Scripts"

Mac OS

1. Install west:

pip3 install -U west

2. Initialize the application and update to fetch modules, including Zephyr:

west init -l app/
west update

tip

This step pulls down quite a bit of tooling, be patient!

3. Export a Zephyr CMake package. This allows CMake to automatically load boilerplate code required for building Zephyr applications.

west zephyr-export

Ubuntu

4. Install the additional dependencies found in Zephyr's requirements-base.txt:

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

Windows

4. Install the additional dependencies found in Zephyr's requirements-base.txt:

pip install -r zephyr/scripts/requirements-base.txt

Mac OS

4. Install the additional dependencies found in Zephyr's requirements-base.txt.

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

4. Install Zephyr SDK

Return to Zephyr's Getting Started Guide and Install Zephyr SDK.

OS-Specific Notes

Windows

dfu-util is required to flash devices that use DFU, but there is currently no maintained package for it on Chocolatey. QMK Toolbox contains a working version of it though.

Raspberry OS

Install cross-compile toolchain

Because Raspberry OS runs on the same architecture (but different ABI) as ARM keyboard MCUs, the operating system's installed cross compilers can be used to target the different ABI. Building for non-ARM MCUs has not been tested.

First, the cross compiler should be installed:

sudo apt install gcc-arm-none-eabi

Next, we'll configure Zephyr with some environment variables needed to find the cross compiler. Create a file named ~/.zephyrrc if it doesn't exist, and add these lines to it:

export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
export CROSS_COMPILE=/usr/bin/arm-none-eabi-

Your setup is now complete.