Here’s How You Can Build Your Own Custom Linux Distro with Yocto

Posted on November 26, 2019 by Luke Ganzevoort

The learning curve for any embedded development tool can be tough. Most people who use complex, powerful tools like this have been through college and spent several years mastering them in day to day life. Yocto is no exception to the list, but the potential to create a robust, custom Linux distribution that meets your needs is game changing. Especially considering where the technical market has been driving the past couple decades.

It’s now easier than ever to host a whole operating system on a small embedded system for a low cost.

At DornerWorks, we believe in simplifying innovation and openly helping you achieve your goals. This blog will help you build your own Linux image with Yocto, providing helpful tips for those who are just getting started.

DornerWorks engineer Luke Ganzevoort has been working with Yocto builds since graduating from Grand Valley State University.
DornerWorks engineer Luke Ganzevoort has been working with Yocto builds since graduating from Grand Valley State University.

Hardware and OS Requirements

The computer that you are building on should have at least 8GB of RAM and 120GB of hard drive space. It can be done with less, but Yocto can be resource intensive, depending on what your end goal is.

The build host should also be running a supported Linux distribution. I recommend Ubuntu. It’s simple to use, has a modern look, and is well maintained. You can also use:

  • Fedora
  • openSUSE
  • CentOS
  • Debian

If you’re using Windows or Mac, checkout VirtualBox which will allow you to run a virtual Linux machine inside your computer.


Let’s start off by making sure you have the correct dependencies installed on your Ubuntu machine. If you are using a distribution other than Ubuntu, visit The Build Host Packages section of the Yocto Project Quick Start guide.

sudo apt-get install gawk wget git-core diffstat unzip \
texinfo gcc-multilib build-essential chrpath socat cpio \
libsdl1.2-dev xterm python python3 python3-pip python3-pexpect \
xz-utils debianutils iputils-ping

Clone Yocto Poky

You can download the latest version of Yocto from the Yocto Project website. It’s probably best to clone the repo with git. This makes it easier to update later and saves time in setup. Currently the command to clone the repo is as follows, which automatically checks out the latest release (the “sumo” branch).

git clone -b sumo git://

You can put this directory anywhere you’d like to. I’d recommend cloning the repo into something like ~/yocto/project-name/. That way you can have a common directory if you ever need to use the same machine for a different Yocto environment.


In order to build anything in Yocto, you need to initialize the environment. Execute the following commands to navigate into the repo that you cloned and initialize the build environment.

cd ~/yocto/project-name/poky
source oe-init-build-env build

This is an easy step but a couple things happen here. Mainly, the build directory is created. This is where all the building is executed and where you can find the image files once the build is complete. The configuration file is also created allowing you to customize your settings.

You don’t need to source the oe-init-build-env every time you build, only when you reboot your computer, or close the shell you’re using.


The configuration file is located in the build directory at poky/build/conf/local.conf. By default this configuration file is set to build for QEMU. You can look over the configuration file. Before building the first time, I recommend adding two lines to the end of the local.conf.


Replace the value “X” in the lines with twice the number of processors/CPUs you have for you computer. For example if there are 4 processors, the lines would look like this BB_NUMBER_THREADS = “8” and PARALLEL_MAKE = “-j 8”. To view the number of processors you have on your machine, use the command lscpu.

Build image

To build the image, enter the command bitbake core-image-sato inside the build directory (poky/build). Bitbake will handle the build, downloading source files it needs and implementing them in the correct places. The first time you build, it will take a while (maybe a couple hours). Sometimes Bitbake does have an error while building. If this happens examine the error. A lot of times it can be caused by an external website being down for a few minutes or it couldn’t find certain source. Usually it’s worth trying to rebuilding the image. Do this by running bitbake core-image-sato again and Yocto will pick up where it left off. Once the build is complete, you can locate the binary images in your build directory at poky/build/tmp/deploy/images/qemux86.


While Yocto can be a difficult tool to master, getting started in the right direction is essential. Pretty soon you’ll be running your own custom Linux distribution on the hardware of your choice! For further help in developing your product see some of our other Yocto resources or contact DornerWorks.

Luke Ganzevoort
by Luke Ganzevoort
Embedded Engineer
Luke Ganzevoort is an embedded engineer at DornerWorks.