Zephyr RTOS: What It Is, How to Install It and Run Your First Build

Who this is for: researchers and lab engineers who need to run firmware experiments on a microcontroller board and want to know what Zephyr is and how to get from a clean machine to a first build. After reading, you should be able to install the Zephyr toolchain from the official instructions, build and flash the Blinky sample, and record enough about your setup for someone else to repeat the work.

Zephyr RTOS is an open-source real-time operating system. Its official introduction describes it as being based on a small-footprint kernel designed for resource-constrained and embedded systems, and it is permissively licensed under the Apache 2.0 license (Zephyr documentation, introduction, read 2026-11-07). In research it is used where an experiment needs deterministic scheduling, a hardware description that travels between boards, and firmware that can be rebuilt from a pinned source tree.

What it is used for in research

Zephyr targets sensor nodes, instrument controllers, wearable prototypes and other devices that cannot run a general-purpose operating system. The documentation lists these capabilities (introduction page, read 2026-11-07):

• Cooperative and preemptive multithreading, interrupts, semaphores, mutexes, message queues and power management.
• Earliest Deadline First (EDF) scheduling and time slicing.
• Userspace and memory protection on x86, ARC and ARM.
• Devicetree to describe hardware, so application code is separated from board details.
• A native networking stack (including LwM2M and BSD sockets) and Bluetooth Low Energy 5.0 including Mesh.
• File systems (ext2, FatFs, LittleFS), logging, a shell and non-volatile storage.
• A native_sim target that runs Zephyr as a Linux application, which lets you test logic without a physical board.

Supported architectures named in the same page include ARC, ARM (Cortex-M, Cortex-A, Cortex-R), Hexagon, x86, MIPS32, OpenRISC, Renesas RX, RISC-V (32 and 64 bit), SPARC V8, Xtensa and TriCore.

Editorial note on reproducibility: because a Zephyr build depends on a source revision, a board name and an SDK version, a methods section should state all three. See computational reproducibility and FAIR4RS for the wider practice, and open source software for licensing background.

Install or access (official source only)

The official getting-started guide is at docs.zephyrproject.org (read 2026-11-07). Its stated requirements:

• Ubuntu 24.04 LTS and later is covered; x86-64 macOS is not supported; native Windows is covered (WSL users follow the Ubuntu steps).
• Minimum versions: CMake 3.28.0, devicetree compiler 1.4.6, and Python 3.12 (strongly recommended).

1. Install dependencies

Ubuntu:

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

Verify with cmake --version, python3 --version and dtc --version.

macOS:

brew install cmake ninja gperf python3 python-tk ccache qemu dtc libmagic wget openocd

Windows:

winget install Kitware.CMake Ninja-build.Ninja oss-winget.gperf Python.Python.3.12 Git.Git oss-winget.dtc wget 7zip.7zip

2. Create the workspace

Ubuntu and macOS:

python3 -m venv ~/zephyrproject/.venv
source ~/zephyrproject/.venv/bin/activate
pip install west
west init -m https://github.com/zephyrproject-rtos/zephyr ~/zephyrproject
cd ~/zephyrproject
west update
west packages pip --install
west zephyr-export

Windows (cmd.exe; in PowerShell use Activate.ps1 instead of activate.bat):

py -3.12 -m venv zephyrproject\.venv
zephyrproject\.venv\Scripts\activate.bat
pip install west
west init -m https://github.com/zephyrproject-rtos/zephyr zephyrproject
cd zephyrproject
west update
cmd /c zephyr\scripts\utils\west-packages-pip-install.cmd
west zephyr-export

3. Install the Zephyr SDK

cd ~/zephyrproject/zephyr
west sdk install

Step-by-step task: build and flash Blinky

1. Activate the virtual environment you created in step 2.
2. List supported boards with west boards and note the exact name of yours.
3. From ~/zephyrproject/zephyr, build the sample: west build -p always -b <your-board-name> samples/basic/blinky. The -p always option forces a pristine build.
4. Connect the board and run west flash. On Linux, the first use of a debug probe may need udev rules installed first, as the guide notes.
5. Record the setup for your methods section: the board name, the Zephyr revision (git rev-parse HEAD inside the zephyr directory), and the SDK version you installed.

To exercise logic with no hardware, the introduction page says Zephyr can run as a Linux application through native_sim; board-specific peripherals will not be present in that mode.

Output and how to read it

A successful west build returns without error and leaves the build in the build directory; a failed one prints the CMake or compiler error that stopped it. A successful west flash completes without error and the board then runs the Blinky sample. Because -p always discards the previous build, results are not carried over from earlier configurations, which is useful when you are comparing two board or SDK settings.

Troubleshooting

These cases come from the official west troubleshooting page (docs.zephyrproject.org, read 2026-11-07).

Symptom	What the documentation says to do
west update fails to fetch	Run west -v update, test the failing git fetch directly, and use curl -v or ssh -v to look for a proxy or firewall problem.
Windows: ‘west’ is not recognized	The pip scripts directory is not on PATH. Add the folder containing west.exe to PATH and reopen cmd.exe.
invalid choice: 'build'	You are outside a west workspace. Run the command inside it or set ZEPHYR_BASE; west help lists the extension commands available.
invalid choice: 'post-init'	west is too old. Upgrade it with pip3 install -U west, back up .west/config, delete .west, and rerun west init.

Free alternatives

Other open-source real-time operating systems exist for the same class of hardware. This table states only what each project says about itself.

Project	What its own site says	Source (read 2026-11-07)
Zephyr	Small-footprint kernel for resource-constrained and embedded systems; Apache 2.0 license.	docs.zephyrproject.org introduction
FreeRTOS	Distributed under the MIT open source license; includes a kernel and a set of libraries.	freertos.org
RIOT	An open-source microcontroller operating system for Internet of Things and other embedded devices, with low memory footprint and real-time capabilities.	doc.riot-os.org

The sites above do not rank one against another, and this page does not either. Choose by the boards, libraries and licence terms your project needs.

FAQ

What is Zephyr RTOS?

It is an open-source real-time operating system built on a small-footprint kernel for resource-constrained embedded systems, licensed under Apache 2.0 (Zephyr introduction, read 2026-11-07).

Which operating systems can I develop on?

The current getting-started guide covers Ubuntu 24.04 LTS and later and native Windows, and states that x86-64 macOS is not supported (read 2026-11-07).

Do I need a physical board?

No for logic testing: the native_sim target runs Zephyr as a Linux application. Hardware-specific behaviour still requires a board.

What does west do?

It is the Zephyr meta-tool used above to initialise the workspace (west init), fetch repositories (west update), build (west build) and flash (west flash).

Sources

• Zephyr Getting Started Guide, read 2026-11-07.
• Zephyr Introduction, read 2026-11-07.
• west Troubleshooting, read 2026-11-07.
• FreeRTOS and RIOT documentation, read 2026-11-07.

Related: electronic lab notebooks for recording build settings alongside experiment data.