This document is a WORK IN PROGRESS.
This is just a quick personal cheat sheet: treat its contents with caution!
This cheat sheet is about managing the official Gentoo kernel:
gentoo-sources. No alternative
kernels (https://wiki.gentoo.org/wiki/Kernel/Overview) will be discussed here.
Table of contents¶
- Kernel in world set
- Kernel update
- Kernel config
- Kernel make and rebuild
- GRUB2 update
- Old kernel removal
- Kernel troubleshooting
Kernel in world set¶
Make sure the current version of your kernel (e.g.
v4.19.72) is part of your
world set, this
way there is no risks for an update to accidentally overwrite it (especially when running
After updating to a newer kernel version (e.g.
v4.19.97), and making sure your system is stable
and does work fine, you can remove the previous kernel from the
world set and add the new one
Emerge new kernel version¶
Backup the current kernel config and clean the kernel before update¶
- Backup and delete most generated files:
- Backup, delete the current
.configand all generated files, then recover
Eventually, you may consider using
# make distclean for removing editor backup files, patch
leftover files and the like.
Kernel update procedure¶
Select the new kernel, change directory into it and copy your kernel
.config file in it:
Now you have to convert your
.config file for the new kernel version. The following configuration
is like the text based configuration with
make config. In order to do this, either use
olddefconfig or use
# make oldconfig.
olddefconfigwill keep all of the options from the old
.configand automatically set the new options to their recommended default values:
syncconfigwill let you decide by entering a value, for each new option, to either install it as built-in (
yvalue), to install it as a module (
mvalue), to not install it (
nvalue), or to print more info (
?value). The recommended/default value will be capitalized (e.g.
make help to see other conversion methods available.
Compare the old and new
.config to see what options have been added:
Compare the old and new
.config to see what options have been removed:
After updating the kernel, don't forget to refer to the below Kernel make and rebuild sub-section.
Then, after rebuilding the kernel, don't forget to refer to the below GRUB2 update sub-section.
After a kernel config, don't forget to refer to the below Kernel make and rebuild sub-section.
Kernel make and rebuild¶
At this point make sure that your boot directory is mounted! Run
$ lsblk, you should find
/boot mount point, if not: mount your boot directory (e.g.
# mount /dev/sda1 /boot).
If you have any external kernel modules, such as binary kernel modules (e.g.
sys-fs/zfs), then they need to be rebuilt for each new kernel:
# eselect kernel set has been made:
If your system does not reboot, you might want to boot on the the SystemRescueCd (see
chroot into your system in order to investigate.
After a successful reboot, and after making sure that your system is stable and does work fine,
don't forget to update your kernel in the
world set: Kernel in
set. After that, you might want to refer to the below Old kernel
Old kernel removal¶
Removing old or unused
gentoo-sources (after switching to newer sources)¶
Before removing old or unused
gentoo-sources, don't forget to update your kernel in the
set: Kernel in
Removing kernel leftovers¶
Before removing kernel leftovers, make sure that your system seems stable and does work fine enough to reboot and to eventually re-install a previous kernel version (if a recover becomes needed).
OR (manual removal)
make cleanwill remove most generated files: the object and kernel object files (ending in
.ko) and a few other things. Leave enough to build external modules
make distcleanremoves editor backup files, patch leftover files and the like
make mrproperwill do everything make clean does, plus remove your
.configfile, the dependency files, and everything else that make config creates
If this cheat sheet has been useful to you, then please consider leaving a star here.