Skip to main content

Environment Setup & West

This guide walks you through setting up a complete Zephyr development environment from scratch, then covers the west commands you'll use every single day.

Workspace location

You can place your Zephyr workspace anywhere on your machine. Throughout this guide we use /your/workspace/path as a placeholder — replace it with wherever you want to keep your workspace (e.g. /home/john/zephyr_ws on Linux, /Users/john/zephyr_ws on macOS or D:\projects\zephyr_ws on Windows).

Minimum tool versions required:

ToolMinimum version
CMake3.20.5
Python3.12
Devicetree compiler (dtc)1.4.6

Step 1 — Install system dependencies​

Update your system first:

sudo apt update && sudo apt upgrade

Install all required packages:

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

On ARM64 systems (e.g. Raspberry Pi), omit gcc-multilib and g++-multilib.

Verify your tool versions:

cmake --version   # must be >= 3.20.5
python3 --version # must be >= 3.12
dtc --version     # must be >= 1.4.6

Step 2 — Create a virtual environment and install west​

West is the meta-tool that ships with Zephyr. It does two things:

  • Workspace management — clones Zephyr and all its dependencies at the exact right versions
  • Build and flash CLI — wraps cmake, ninja, and your programmer into single commands

Install it inside a Python virtual environment to keep it isolated from your system Python.

python3 -m venv /your/workspace/path/.venv
source /your/workspace/path/.venv/bin/activate
pip install west
Activate the virtual environment every session

The virtual environment is not activated automatically. Every time you open a new terminal and want to work with your Zephyr workspace, run the activate command first:

  • Linux / macOS: source /your/workspace/path/.venv/bin/activate
  • Windows (PowerShell): D:\your\workspace\path\.venv\Scripts\Activate.ps1

Your prompt will show (.venv) when the environment is active.

Verify west is installed:

west --version
# west, version 1.x.x

Step 3 — Initialize the Zephyr workspace​

This step clones Zephyr v4.4.0 and all its dependencies (HALs, modules, bootloader). Expect 2–3 GB of downloads — it only runs once per workspace.

west init -m https://github.com/zephyrproject-rtos/zephyr --mr v4.4.0 /your/workspace/path
cd /your/workspace/path
west update
west zephyr-export
note

Always use west init instead of git clone. West registers the manifest so that west update always restores the exact dependency tree — your project will build correctly years from now.

Install the Python dependencies:

west packages pip --install

Step 4 — Install the Zephyr SDK​

The SDK contains the toolchains for ARM, RISC-V, Xtensa, and all other supported architectures.

cd /your/workspace/path/zephyr
west sdk install

west sdk install automatically downloads and sets up the correct SDK version for your Zephyr checkout.


Step 5 — Verify the installation​

Build the blinky sample for your board. Replace <your-board> with your actual board name (e.g. esp32s3_devkitc/esp32s3/procpu, nrf52840dk/nrf52840):

cd /your/workspace/path/zephyr
west build -p always -b <your-board> samples/basic/blinky

If the build completes without errors, your environment is ready.


Serial console — VS Code setup​

To read printf / printk output from your board over USB, install the Serial Monitor extension in VS Code and set up the USB serial driver for your platform.

Install the extension:

Open VS Code, go to the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X), and search for Serial Monitor by Microsoft.

VS Code Serial Monitor extension

On Linux, serial port access requires adding your user to the dialout group:

sudo usermod -aG dialout $USER

Log out and back in for the change to take effect. Then verify:

groups | grep dialout

Linux includes CP210x, CH340, and FTDI drivers in the kernel — no additional installation needed.

Open the Serial Monitor in VS Code (Terminal → Serial Monitor), select the correct port, set the baud rate to 115200, and connect.


Official reference

docs.zephyrproject.org — Getting Started Guide