Last Updated on December 17, 2025
Objectives
This blog post aims to point out a well-known and documented issue with kernel modules not ending up on the root file system, which is likely overseen by people until they stumble over it. But even though it is documented, there might be some more subtle issues.
Kernel module(s)
So you created a new kernel module. You want to include all kernel modules in the root file system, or maybe just one of them. But something seems to be not working.
You reach out to the community mailing list or chat and write something like this:
# I have in my machine configuration:
MACHINE_EXTRA_RRECOMMENDS += "kernel-modules"
# When I look into the rootfs I see no modules installed in /lib/modules/$(uname -r).
# I get only a modules tarball in the deploy directory.
# I also tried
MACHINE_EXTRA_RDEPENDS += "kernel-modules"
# and it still does not work.
# What am I doing wrong?Search in the “Mega Manual”
If things don’t work as expected, check out the good old “Mega Manual“, which you should read every night before falling asleep. Don’t forget to have the “BitBake Manual” handy (remember, it’s not part of the “Mega Manual“).
MACHINE_EXTRA_RRECOMMENDS
Will be installed in an image: A list of machine-specific packages. They are not essential for booting the machine. The image being built has no build dependency on this list of packages.
This variable is only relevant for images that are based on the package group: packagegroup-base. core-image-minimal or core-image-full-cmdline are excluded.
This variable is similar to MACHINE_EXTRA_RDEPENDS. However, there is no build dependency between the ‘image’ and the list of packages declared in the variable above. In other words, the image will build even if a file in this list is not found.
An example is a machine with Wi-Fi capability that is not essential for the machine to boot the image. However, if you are building a more fully-featured image, you want to enable Wi-Fi. In this case, the package containing the Wi-Fi kernel module will not be produced if the Wi-Fi driver is built into the kernel. But you still want the build to succeed instead of failing as a result of the package not being found. To accomplish this, assuming the package for the module was called kernel-module-examplewifi.
machine.conf – Add the following line:
MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"MACHINE_EXTRA_RDEPENDS
A list of machine-specific packages to install as part of the image we build. They are not essential for the machine to boot. However, the build process for more fully featured images depends on the packages being present.
This variable is only relevant for images that are based on the package group: packagegroup-base. core-image-minimal or core-image-full-cmdline are excluded.
The variable is similar to the MACHINE_EXTRA_RRECOMMENDS variable, with the exception that the image being built has a build dependency on the variable’s list of packages. In other words, the image will not build if a file in this list is not found.
An example is a machine with Wi-Fi capability that is not essential for the machine to boot the image. However, if you are building a more fully featured image, you want to enable the Wi-Fi. The package containing the firmware for the Wi-Fi hardware is always expected to exist, so it is acceptable for the build process to depend upon finding the package. To accomplish this, assuming the package for the module was called wifidriver-firmware.
machine.conf – Add the following line:
MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"In plain English
A bit exaggerated: “If the weather is right. In case, the moon is in the seventh house. And if the final ‘Image’ is derived from packagegroup-base, then BitBake will take those variables into account, otherwise – Nope.”
So the reason it didn’t work is, that you built something like core-image-minimal or core-image-full-cmdline.
And you installed kernel-modules with those variables:
Quick and dirty solution
Use a different variable. Maybe something like:
MACHINE_ESSENTIAL_EXTRA_RDEPENDS
A list of required machine-specific packages to install as part of the image being built. The build process depends on the presence of these packages. Furthermore, because this is a “machine-essential” variable, the package list is essential for the machine to boot. This variable affects images derived from packagegroup-core-boot. This means also: core-image-minimal.
The variable is similar to the MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS variable, with the exception that the image being built has a build dependency on the variable’s list of packages. In other words, the image will not build if a file in this list is not found.
For example, suppose the machine definition you use for the build requires example-init to be run during boot to initialize the hardware.
machine.conf – Add the following line:
MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"Less quick and dirty solution
The “upstream machine configuration” of a “Beaglebone Black” was in the bad old days like this. The interesting part is here:
MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree"
...
MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "kernel-image kernel-devicetree"What you see above: kernel-devicetree in MACHINE_EXTRA_RRECOMMENDS and MACHINE_ESSENTIAL_EXTRA_RDEPENDS – makes no sense. MACHINE_ESSENTIAL_EXTRA_RDEPENDS will win. But kernel-modules are, by definition, not essential for booting the machine. They should be added to MACHINE_EXTRA_RRECOMMENDS. And this seems to be the difference between ESSENTIAL and RRECOMMENDS. The variables kernel-image and kernel-devicetree are needed for the machine to boot so they should be added to MACHINE_ESSENTIAL_EXTRA_RDEPENDS and this is what happens now.
MACHINE_EXTRA_RRECOMMENDS = "kernel-modules"
...
MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "kernel-image kernel-devicetree"What if you want to build something small, e.g., core-image-minimal but you want it with kernel modules?
They will not be added with:
MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree"They will be added, but they are not essential for booting:
MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "kernel-image kernel-devicetree"How to get your kernel modules onto your root file system? Modify e.g., your conf/local.conf and add this line:
IMAGE_INSTALL:append = " kernel-modules"What if you don’t want all “in-tree kernel modules” installed
If you do something like this:
MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "kernel-modules"Then you will get all kernel-modules into your root file system, which might not be what you want.
You might wonder how to include a single kernel module, whether in-tree or out-of-tree. Kernel-modules is a meta package that is magically created and contains all the kernel modules. But don’t forget that each kernel module is contained in a single package.
Something like this:
student@e450-tr1:/workdir/build/multi-v7-ml-virt/tmp/deploy$ find | grep kernel-module
./ipk/multi_v7_ml/kernel-module-at91-can-5.4.47-custom-ml-virt_5.4.47-custom-ml-virt+git0+fd8cd8ac94-r0.4_multi_v7_ml.ipk
./ipk/multi_v7_ml/kernel-module-led-class-flash-5.4.47-custom-ml-virt_5.4.47-custom-ml-virt+git0+fd8cd8ac94-r0.4_multi_v7_ml.ipk
...
./ipk/multi_v7_ml/kernel-module-qt1070-5.4.47-custom-ml-virt_5.4.47-custom-ml-virt+git0+fd8cd8ac94-r0.4_multi_v7_ml.ipk
./ipk/multi_v7_ml/kernel-module-xt-length-5.4.47-custom-ml-virt_5.4.47-custom-ml-virt+git0+fd8cd8ac94-r0.4_multi_v7_ml.ipk
./ipk/multi_v7_ml/kernel-module-ebt-ip-5.4.47-custom-ml-virt_5.4.47-custom-ml-virt+git0+fd8cd8ac94-r0.4_multi_v7_ml.ipk
student@e450-tr1:/workdir/build/multi-v7-ml-virt/tmp/deploy$ You could install just a single package, e.g., “kernel-module-led-class-flash” instead of the meta package “kernel-modules” if that’s what you wanted.
Conclusion
Read the fine print carefully, ask, and experiment. You are certainly not the first to stumble over this problem. In the bad old days, it was even worse: Kernel-modules were installed in core-image-minimal or core-image-full-cmdline through MACHINE_EXTRA_RRECOMMENDS. But this behavior was changed with the Morty Release in Nov. 2016 if I remember well.
Appendix
For a blog post that describes how to build the upstream kernel without the Yocto Project® take a look here. If you want to learn how Embedded Linux works, take a look here. To learn more about the Yocto Project® take a look here.
