Yocto Project: how to build a custom Linux for a device

Yocto Project — an open project that helps build custom Linux systems for embedded devices, regardless of CPU architecture. It is not a distribution, but a set of tools and metadata: from source code an image is built that contains exactly the packages, kernel and settings needed for a specific device — a controller, terminal, gateway, media set-top box.

What it consists of

• BitBake — the task scheduler and executor. It reads recipes and configuration, builds the dependency tree and performs the build, much like make.
• OpenEmbedded — the build system that uses BitBake to build packages and the full image.
• Recipes (files .bb) — a description of how to build one component: where to get sources, which patches to apply, what it depends on, how to compile it.
• Layers — sets of recipes and configuration, whose names usually start with meta-. Layers are added as needed: board support, graphics subsystem, custom applications.
• BSP layer (Board Support Package) — a layer with settings for specific hardware, for example meta-raspberrypi for Raspberry Pi boards.
• Poky — the reference Yocto build. The documentation explicitly warns: it should not be used as a finished product in its raw form; it is a starting point.

Releases and support

According to the project’s wiki as of September 2026, the following are supported:

The next release, 6.1 Blacksail, is scheduled for October 2026 with six months of support. For a product that will live for years, choose the LTS branch and all layers from the same branch: layers from different versions are not compatible with each other.

First build

The minimal path is to follow the Quick Build guide in the Yocto documentation. The build is resource-intensive: the documentation states at least 140 GB of free disk space and recommends 32 GB of RAM. You need a supported Linux distribution, Git, Python 3.9 or newer, gcc 10.1 or newer, plus the set of packages listed in the guide for each distribution.

The current version of the guide uses the bitbake-setup utility:

python3 -m venv --clear ./bitbake-setup-venv
. ./bitbake-setup-venv/bin/activate
pip install bitbake-setup
bitbake-setup init

Then the build environment is activated by the init-build-env script from the created directory, the default target machine is the qemux86-64 emulator, and an image is built:

bitbake core-image-minimal
runqemu snapshot

core-image-minimal is a minimal image that only boots and provides a console. The guide for the first build shows a fuller core-image-sato with a graphical shell. The first build takes several hours; subsequent builds are noticeably faster thanks to the cache.

Building for a real device

For a specific board, its BSP layer is added. For Raspberry Pi this is meta-raspberrypi: it depends on BitBake, OpenEmbedded-Core and meta-yocto, and the layer’s README suggests the shortest path — the kas utility, which uses a single YAML file to download the needed layers and start the build. The finished image is written to an SD card with the bmaptool utility. It’s important to use the layer branch that matches the Yocto branch.

Where Yocto is useful

• Mass-produced devices. Each unit receives an identical, reproducible system.
• Control over contents. The image has no unnecessary packages, which means smaller size, faster boot and a smaller attack surface.
• Licensing and audit. The build system knows the license of each component, which simplifies audits before product release.
• Long-term support. An LTS branch with four years of support allows planning updates for the device’s lifetime.

When Yocto is not needed

• For a server or workstation: a standard distribution like Debian is simpler and more familiar.
• For a prototype of one or two devices: it’s faster to use a ready image for the board, for example Raspberry Pi OS.
• If the team doesn’t have time to learn: Yocto has a steep learning curve; the first working build of your own image can take weeks.
• For a router or firewall: ready-made systems — OpenWrt, OPNsense — solve these tasks without a custom build.

Yocto pays off when a device is produced in series, lives for years, and must run a precisely known set of software.