Yocto Project Complete Beginner's Guide: Your First Custom Linux Build

"I want to run a custom Linux on my Raspberry Pi or Jetson."

"I need a custom Linux distro for an IoT product I'm building."

"I keep hearing about Yocto, but I have no idea where to start."

If any of these sound familiar, this guide is for you. I'll walk you through everything — from the absolute basics of Yocto Project all the way to building and booting your first Linux image.

I've been working in embedded Linux development for over ten years. Yocto has a steep learning curve at first, but once the underlying concepts click, it becomes remarkably flexible and powerful. By the end of this article, you'll have your first custom Linux image up and running.

What You'll Learn

• What Yocto Project is and why it exists
• How BitBake, layers, and recipes work
• How to set up your development environment
• Step-by-step: building your first Linux image
• How to verify your build with QEMU

What Is Yocto Project?

Yocto Project is an open-source project for creating custom Linux distributions tailored to embedded devices.

The key point: Yocto itself is not an OS. Think of it as a toolbox for building Linux systems.

The Problems Yocto Solves

Embedded Linux development comes with a unique set of challenges:

• Limited storage (a few MB to a few GB) — you need to strip out unnecessary packages
• Underpowered CPUs (ARM Cortex-A, etc.) — the system needs to be lightweight
• Specialized hardware (custom drivers) — the kernel needs customization
• Long product lifecycles (some products run for 10+ years) — reproducible builds are essential

Yocto is the de facto standard build system that addresses all of these at once.

Yocto vs. Buildroot vs. OpenWRT

Bottom line: If you're building commercial products or IoT devices, learning Yocto is worth the investment. Nearly every major semiconductor vendor ships their SDK built on Yocto.

Who Uses Yocto?

• Intel — Edison, Minnowboard
• NXP — Official BSP for the i.MX series
• Texas Instruments — Sitara processor family
• Sony — Digital cameras, audio equipment
• Automotive Grade Linux (AGL) — The standard for in-vehicle Linux

The Four Core Concepts of Yocto

To understand Yocto, you need to get comfortable with four fundamental ideas.

1. Poky (the Reference Distribution)

Poky is Yocto Project's reference implementation — think of it as the starter template.

When you begin with Yocto, you start by downloading Poky. It ships with everything you need: BitBake, the base layers, and sample images.

2. BitBake (the Build Engine)

BitBake is the engine that actually runs your builds. Instead of Makefiles, it reads "recipes," resolves dependencies, and executes the build tasks in the right order.

# Build a minimal Linux image
$ bitbake core-image-minimal

# Build just one package
$ bitbake busybox

# Inspect package metadata
$ bitbake -e busybox | grep ^PV=

3. Layers

Layers are directories that group related recipes and configuration. They're what makes Yocto so modular and maintainable.

• meta — OpenEmbedded core layer
• meta-poky — Poky-specific configuration
• meta-raspberrypi — Raspberry Pi BSP
• meta-mylayer — Your own customizations

By stacking layers, you can customize any aspect of the system without touching the base layers. This separation is one of Yocto's greatest strengths.

4. Recipes

Recipes are .bb files that describe how to build a specific piece of software.

# Example: hello-world_1.0.bb
SUMMARY = "Hello World sample application"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

SRC_URI = "file://hello.c"

S = "${WORKDIR}"

do_compile() {
    ${CC} ${CFLAGS} ${LDFLAGS} -o hello ${WORKDIR}/hello.c
}

do_install() {
    install -d ${D}${bindir}
    install -m 0755 hello ${D}${bindir}
}

Setting Up Your Development Environment

Recommended System Specs

Yocto builds are resource-intensive. The better your hardware, the less time you'll spend waiting.

Installing Required Packages (Ubuntu 22.04)

# Install all required build dependencies
$ sudo apt update
$ sudo apt install -y gawk wget git diffstat unzip texinfo gcc build-essential \
    chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils \
    iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev \
    python3-subunit mesa-common-dev zstd liblz4-tool file locales

# Set up locale (en_US.UTF-8 is required)
$ sudo locale-gen en_US.UTF-8

Downloading Poky

# Create a working directory
$ mkdir -p ~/yocto && cd ~/yocto

# Clone Poky (scarthgap = current LTS branch, supported until ~2027)
$ git clone -b scarthgap git://git.yoctoproject.org/poky.git

# Verify the download
$ ls poky/
bitbake  documentation  meta  meta-poky  meta-yocto-bsp  oe-init-build-env  scripts

scarthgap is the Yocto 5.0 LTS release, supported until approximately 2027 — this is the recommended branch for production use. If you need the latest features, styhead (Yocto 5.1) is available, but it is a non-LTS release with a shorter support window.

Running Your First Build

Initializing the Build Environment

$ cd ~/yocto/poky
$ source oe-init-build-env build

# After running this, you'll be automatically moved to the build/ directory
# You'll see a message like:
You had no conf/local.conf file. This configuration file has therefore been
created for you...

Important: always use source, not bash or ./. The script sets environment variables that need to persist in your current shell session.

Configuring local.conf

Edit conf/local.conf to tune the build parallelism.

$ nano conf/local.conf

# Add these lines, adjusting to your CPU core count
BB_NUMBER_THREADS = "8"
PARALLEL_MAKE = "-j 8"

# Target machine (default is qemux86-64 for QEMU testing)
MACHINE ?= "qemux86-64"

BB_NUMBER_THREADS controls how many BitBake tasks run in parallel. PARALLEL_MAKE controls the -j flag passed to make. Setting both to your CPU core count is a good starting point.

Running the Build

# Build the minimal Linux image
$ bitbake core-image-minimal

# First builds take 1-3 hours depending on your hardware
# If a build fails partway through, just run the same command again — BitBake resumes from where it left off

On the first run, BitBake downloads all source code and compiles everything from scratch. Subsequent builds are much faster thanks to the shared state cache.

Build Time Reference

Testing Your Build with QEMU

Using runqemu

Once the build finishes, you can launch your Linux image in an emulator — no physical hardware needed.

# Launch the image in QEMU
$ runqemu qemux86-64

# Launch without a graphical window (serial console only)
$ runqemu qemux86-64 nographic

# After boot, log in as root (no password)
qemux86-64 login: root
root@qemux86-64:~#

Verifying the System

# Check the kernel version
root@qemux86-64:~# uname -a
Linux qemux86-64 6.6.x-yocto-standard #1 SMP ...

# Check disk usage — notice how small the root filesystem is
root@qemux86-64:~# df -h
Filesystem      Size  Used Avail Use% Mounted on
/dev/root        48M   32M   14M  70% /

# List installed packages
root@qemux86-64:~# opkg list-installed

# Shut down
root@qemux86-64:~# poweroff

Congratulations — you just built and booted a custom Linux image with Yocto!

What's Next?

Now that you have the basics down, the next steps are:

• Add layers: Bring in a BSP layer like meta-raspberrypi and target real hardware
• Write your own recipes: Package your application and include it in the image
• Deploy to a real device: Get Yocto Linux running on a Raspberry Pi or Jetson

Summary

Here's what we covered in this article:

• Yocto is a toolbox for building custom embedded Linux systems — not an OS itself
• The four core components are Poky, BitBake, layers, and recipes
• On Ubuntu, bitbake core-image-minimal builds a working Linux image
• runqemu lets you test your image without any hardware

Yes, Yocto has a steep learning curve. But once you have it down, you'll be able to build Linux for virtually any embedded device — and that's a skill that translates directly to high-value work in IoT, automotive, and industrial electronics.

Related Articles

• How to Write Custom Yocto Recipes: A Complete .bb File Guide
• Creating and Adding Yocto Layers: Understanding meta-xxx
• Building Linux for Raspberry Pi with Yocto

This article reflects the state of Yocto Project as of January 2026. Procedures may change as new versions are released. Check the Yocto Project official site for the latest information.