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 24.04 LTS and later. If you are using a different Linux distribution see Install Linux Host Dependencies.

sudo apt update
sudo apt upgrade

Install dependencies

Next, install the host tools Zephyr needs to configure and build applications. The instructions below use the recommended package manager for each operating system so the tools are available from your terminal.

The current minimum required versions for the main dependencies are:

Tool

Min. Version

CMake

3.20.5

Python

3.12

Devicetree compiler

1.4.6

Note

Python 3.12 is strongly recommended. Using a newer Python release may fail on some systems, for example when installing the required packages on Windows.

  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-venv python3-tk \
  xz-utils file make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1

    Note

    Due to the unavailability of gcc-multilib and g++-multilib on AArch64 (ARM64) systems, you may need to omit them from the list of packages to install.

  2. Verify the versions of the main dependencies installed on your system by entering:

    cmake --version
python3 --version
dtc --version

    Check those against the versions in the table in the beginning of this section. Refer to the Install Linux Host Dependencies page for additional information on updating the dependencies manually.

Get Zephyr and install Python dependencies

Next, use west to create a workspace and fetch Zephyr together with its modules.

These commands use zephyrproject as the workspace name; you can choose another name and location. You will also install Zephyr’s Python dependencies in a Python virtual environment so they stay separate from your system Python installation.

  1. Create a new virtual environment:

    python3 -m venv ~/zephyrproject/.venv

  2. Activate the virtual environment:

    source ~/zephyrproject/.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 a new terminal session before working with Zephyr. If you don’t, commands such as west will not be found, or may run against a different Python environment, leading to confusing errors.

  3. Install west:

    West is Zephyr’s workspace manager; the next commands use it to create and update the workspace.

    pip install west

  4. Get the Zephyr source code:

    west init creates a west workspace and clones https://github.com/zephyrproject-rtos/zephyr as its manifest repository.

    west update then fetches the various west projects (modules) listed in Zephyr’s west manifest (hardware abstraction layers (HALs), libraries, etc.).

    west init -m https://github.com/zephyrproject-rtos/zephyr ~/zephyrproject
cd ~/zephyrproject
west update

    Tip

    To reduce disk space usage and avoid downloading unnecessary modules or vendor HALs during setup, you may configure Project Groups before running west update.

  5. Export a Zephyr CMake package. This registers your current Zephyr checkout in CMake’s user package registry so find_package(Zephyr) can locate it automatically when building applications.

    west zephyr-export

  6. Install Zephyr’s Python dependencies:

    west packages reads the Python requirements from the checked-out Zephyr workspace (including its modules), so the installed packages match the Zephyr version you fetched.

    west packages pip --install

    Note

    Installing these dependencies can downgrade or upgrade west itself.

Install the Zephyr SDK

The Zephyr Software Development Kit (SDK) contains toolchains for each of Zephyr’s supported architectures. Those toolchains include the compiler, assembler, linker, and other programs required to build Zephyr applications for your target hardware.

It also contains additional host tools, such as custom QEMU and OpenOCD builds that are used to emulate, flash and debug Zephyr applications.

Install the Zephyr SDK with west sdk install from the Zephyr repository:

cd ~/zephyrproject/zephyr
west sdk install

Tip

Use command options to choose the SDK installation destination or install only selected architecture toolchains. See west sdk install --help for details.

Note

If you want to install Zephyr SDK without using the west sdk command, please see Zephyr SDK installation.

Build the Blinky Sample

Note

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

If you are unsure what name west uses for your board, use west boards to list all boards Zephyr supports. Your board’s Board Catalog also shows the exact board target name to pass to west build.

Build the Blinky with west build. Replace <your-board-name> with the name of your board:

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

The -p always option forces a pristine build, which removes build output from any previous configuration. This avoids stale files when you are getting started. Later, you can use -p auto to let west build heuristics decide when a pristine build may be needed. See west build -h for details.

Note

A board may contain one or multiple SoCs and each SoC may contain one or more CPU clusters. When building for such boards, specify the SoC or CPU cluster for which the sample must be built. For example to build Blinky for the cpuapp core on the nRF5340 DK the board must be provided as: nrf5340dk/nrf5340/cpuapp. See also Board terminology for more details.

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 and Shields, as some boards require a specific setup or procedure to flash them.

Flash the sample with west flash. This programs the application you just built onto the connected board:

west flash

Note

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.

Note

On Linux, you may need to configure udev rules before flashing with a debug probe for the first time. See Setting udev rules.

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

../../_images/ReelBoard-Blinky.webp

Phytec reel_board running blinky

Next Steps

Here are some next steps for exploring Zephyr:

Asking for Help

Before asking for help, search this documentation, the Zephyr project’s GitHub discussions and issues, and Discord chat history. Your question may already have an answer there. You can also ask the chatbot available from every page of this documentation.

When asking for help, include:

  1. What you want to do

  2. What you tried, including the commands you ran

  3. What happened, including the full text output

Copy and paste text instead of sharing screenshots. For more than 5 lines of terminal output, source code, or logs on Discord or GitHub, create a snippet using three backticks.