Getting Started Guide

Follow this guide to:

  • Set up a command-line Zephyr development environment on Ubuntu, macOS, or Windows (instructions for other Linux distributions are discussed in Install Linux Host Dependencies)

  • Get the source code

  • Build, flash, and run a sample application

Select and Update OS

Click the operating system you are using.

This guide covers Ubuntu version 18.04 LTS and later.

sudo apt update
sudo apt upgrade

Install dependencies

Next, you’ll install some host dependencies using your package manager.

  1. Use apt to install the required dependencies:

    sudo apt install --no-install-recommends git cmake ninja-build gperf \
      ccache dfu-util device-tree-compiler wget \
      python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \
      make gcc gcc-multilib g++-multilib libsdl2-dev
  2. Verify the version of cmake that is installed on your system by entering:

    cmake --version

    The version must be 3.13.1 or later. If your version is older, complete the following steps to add the Kitware third-party apt repository, which contains an updated version of cmake.

    1. Add the Kitware signing key:

      wget -O - 2>/dev/null | sudo apt-key add -
    2. Add the Kitware apt repository for your OS release. For Ubuntu 18.04 LTS:

      sudo apt-add-repository 'deb bionic main'
    3. Then install the updated version of cmake with apt:

      sudo apt update
      sudo apt install cmake

Get Zephyr and install Python dependencies

Next, clone Zephyr and its modules into a new west workspace named zephyrproject. You’ll also install Zephyr’s additional Python dependencies.

  1. Install west, and make sure ~/.local/bin is on your PATH environment variable:

    pip3 install --user -U west
    echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
    source ~/.bashrc
  2. Get the Zephyr source code:

    west init ~/zephyrproject
    cd ~/zephyrproject
    west update
  3. Export a Zephyr CMake package. This allows CMake to automatically load boilerplate code required for building Zephyr applications.

    west zephyr-export
  4. Zephyr’s scripts/requirements.txt file declares additional Python dependencies. Install them with pip3.

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

Install a Toolchain

A toolchain provides a compiler, assembler, linker, and other programs required to build Zephyr applications.

The Zephyr Software Development Kit (SDK) contains toolchains for each of Zephyr’s supported architectures. It also includes additional host tools, such as custom QEMU binaries and a host compiler.

  1. Download the latest SDK installer:

    cd ~
  2. Run the installer, installing the SDK in ~/zephyr-sdk-0.12.4:

    chmod +x
    ./ -- -d ~/zephyr-sdk-0.12.4


    It is recommended to install the Zephyr SDK at one of the following locations:

    • $HOME/zephyr-sdk[-x.y.z]

    • $HOME/.local/zephyr-sdk[-x.y.z]

    • $HOME/.local/opt/zephyr-sdk[-x.y.z]

    • $HOME/bin/zephyr-sdk[-x.y.z]

    • /opt/zephyr-sdk[-x.y.z]

    • /usr/zephyr-sdk[-x.y.z]

    • /usr/local/zephyr-sdk[-x.y.z]

    where [-x.y.z] is optional text, and can be any text, for example -0.12.4.

    If installing the Zephyr SDK outside any of those locations, please read: Install the Zephyr Software Development Kit (SDK)

    You cannot move the SDK directory after you have installed it.

  3. Install udev rules, which allow you to flash most Zephyr boards as a regular user:

    sudo cp ~/zephyr-sdk-0.12.4/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
    sudo udevadm control --reload

Build the Blinky Sample


Blinky is compatible with most, but not all, Supported Boards. If your board does not meet Blinky’s Requirements, then Hello World is a good alternative.

Build the Blinky with west build, changing <your-board-name> appropriately for your board:

cd ~/zephyrproject/zephyr
west build -p auto -b <your-board-name> samples/basic/blinky

The -p auto option automatically cleans byproducts from a previous build if necessary, which is useful if you try building another sample.

Flash the Sample

Connect your board, usually via USB, and turn it on if there’s a power switch. If in doubt about what to do, check your board’s page in Supported Boards.

Then flash the sample using west flash:

west flash

You may need to install additional host tools required by your board. The west flash command will print an error if any required dependencies are missing.

If you’re using blinky, the LED will start to blink as shown in this figure:


Phytec reel_board running blinky

Next Steps

Here are some next steps for exploring Zephyr: