Gentoo Linux Kernel Upgrade Guide
The kernel is one of the few package classes in portage that requires some
manual intervention to complete the upgrade. Portage will download and
install the kernel source for you, but then it is up to you to step in and
compile the new kernel before any changes will take effect.
Although this guide is targeted at users upgrading from one kernel release
to another, it will also be useful for users migrating from one kernel
package to another.
gentoo-sources is used as an example in this document, however, the
instructions here also apply to the other packages present in our tree.
Why upgrade the kernel?
Generally, upgrading from one minor kernel release to the next won't bring any
major differences. There are several reasons to upgrade the kernel. One is to
take advantage of a specific new feature or driver; another is to be protected
against a security vulnerability, or just to maintain an up-to-date and healthy
Even if you choose not to update to every new kernel revision, it is
recommended that you at least upgrade from time to time. It is strongly
recommended that you immediately upgrade to a new kernel if that new release
solves a security problem.
Obtaining the newer sources through Portage
You upgrade the kernel sources like you would upgrade any other package -
using the emerge utility. It will probably be the case that you want to
upgrade your kernel when you see the upgrade appearing on your world updates
list. For example:
Code Listing 3.1: New kernel sources appearing on update list
# emerge -Dup world
Calculating dependencies ...done!
[ebuild NS ] sys-kernel/gentoo-sources-2.6.39-r3 [2.6.38-r6]
The "NS" label in the above output means that the new kernel will be installed
in a New Slot, i.e. the sources of your old kernel will be kept around, until
you manually remove them.
You can then go ahead and install the update, e.g.:
Code Listing 3.2: Upgrading your kernel sources
# emerge -u gentoo-sources
The kernel sources will then be installed into a subdirectory of
/usr/src. In the above example, the new kernel sources will be
installed at /usr/src/linux-2.6.39-gentoo-r3.
Updating the /usr/src/linux symbolic link
Gentoo requires that the /usr/src/linux symbolic link points to
the sources of the kernel you are running.
Portage can update the symlink automatically when you emerge new kernel
sources. All you have to do is add the symlink flag to the USE variable
Code Listing 4.1: Example of USE variable in /etc/portage/make.conf
USE="symlink x86 3dnow 3dnowex X aac aalib adns alsa apache2"
Alternatively, you could use app-admin/eselect to modify the symlink.
Code Listing 4.2: Using eselect to symlink
# emerge eselect
# eselect kernel list
Available kernel symlink targets:
 linux-2.6.38-gentoo-r6 *
# eselect kernel set 1
# eselect kernel list
 linux-2.6.39-gentoo-r3 *
If you really want to do it yourself, the following example shows you how to
make the link point to linux-2.6.39-gentoo-r3:
Code Listing 4.3: Updating the /usr/src/linux softlink manually
# cd /usr/src
# ln -sfn linux-2.6.39-gentoo-r3 linux
Configuring, compiling and installing the new kernel
For either of these options, you should refer to the instructions given in the
Gentoo Handbook relating to Configuring
the Kernel and Configuring the Bootloader. Below is an outline of
the required actions:
Option 1: Automatic kernel setup with Genkernel
If you are a genkernel user, you just need to repeat the stages you went
through when installing your kernel for the first time.
Simply run genkernel in the normal way:
Code Listing 5.1: Invoking genkernel
# genkernel all
You can also use extra parameters for other genkernel functionality. For
example, if you wish to configure some extra kernel options using
menuconfig and you wish genkernel to automatically update your grub boot
loader configuration, then invoke genkernel as follows:
Code Listing 5.2: Invoking genkernel with some common arguments
# genkernel --menuconfig --bootloader=grub all
For more info, follow the Gentoo Linux
Genkernel Guide, or refer to the Gentoo
Handbook. Many of the options can be set in the configuration file for
genkernel, /etc/genkernel.conf. Also take a look at the Gentoo Linux Initial RAM file system
Option 2: Manual configuration
To begin, open the menuconfig utility in the kernel source tree:
Code Listing 5.3: Invoking menuconfig
# cd /usr/src/linux
# make menuconfig
Select the options required for your hardware and operating environment. For
additional information on kernel configuration, refer to the chapter entitled
Configuring the Kernel of the Gentoo Handbook.
Next, compile your kernel and copy it over to your boot partition. Again,
follow the Gentoo Handbook
instructions outlined in the chapter on Configuring the Bootloader. If
/boot is a separate partition, ensure it is mounted before copying
the compiled kernel to this directory! Failing to do so would keep you from
booting the system with your new kernel.
Code Listing 5.4: Compiling and installing the new kernel
# make && make modules_install
# mount /boot
# cp arch/i386/boot/bzImage /boot/bzImage-2.6.39-gentoo-r3
Finally, you should update your boot loader configuration, adding an entry for
the new kernel (don't delete the old one just yet!) and unmount the
/boot partition. Again, refer to the
for detailed instructions on this procedure.
Reinstalling external modules
If you use any kernel modules that are not included in the kernel source tree
but are provided elsewhere in Portage (e.g. ALSA drivers and NVIDIA or ATI
graphics drivers), then you must reinstall these after upgrading the kernel.
This is as simple as re-merging the packages involved. For more information,
refer to the chapter on Configuring the Kernel in the Gentoo Handbook.
We provide you with an easy tool (sys-kernel/module-rebuild) which
rebuilds all the kernel modules you have installed using separate ebuilds for
the kernel at /usr/src/linux. Its use is straightforward. After
emerging it, simply run module-rebuild populate to populate the
database with a list of packages that will need to be rebuilt after upgrading
the kernel. Once you have finished upgrading or recompiling your kernel, run
module-rebuild rebuild to rebuild the drivers for your new kernel.
For more information, run module-rebuild without any options to see a
list of commands that can be passed to the utility.
Updating your module configuration
If you have put specific module configuration entries in
/etc/conf.d/modules, then you might need to update the entries
Code Listing 7.1: Sample /etc/conf.d/modules file
Rebooting into the new kernel
Next, close all applications and reboot your system. If you followed the above
instructions correctly, the boot loader menu should include an entry for the
new kernel. Select the new kernel and let the system boot.
Hopefully, your system successfully boots with the new kernel, and you can log
in to resume whatever you were doing. If this is the case, then the upgrade is
If you made a mistake and the system fails to boot with the new kernel, reboot
the system and select the entry from the boot loader that corresponds to the
last known working kernel. You can then restart from the
Configuring, compiling, and installing the new kernel stage -- making
the appropriate changes to correct your mistake. In some cases, you might not
even need to reboot to do this (e.g. you missed a driver for an audio device,
Ethernet adapter, etc.)
Running multiple kernels
You may have noticed, that when installing the sources for your newer kernel,
the sources for your existing kernel were not removed. This is by design -- it
allows you to easily switch between running different kernels.
Switching between multiple kernels is as simple as leaving the kernel sources
under /usr/src/ and leaving the bzImage binaries on
your /boot partition (referenced by entries in your boot loader
configuration). Every time you boot up, you will be presented with a choice of
which kernel to boot into.
Removing older kernels
Continuing on from the last section, you may be happy with your new kernel and
not have any need to keep older kernel versions around. To easily remove all
sources for a particular kernel except for the newest one, you can take
advantage of the prune option available through emerge. Continuing
the example using gentoo-sources:
Code Listing 10.1: Pruning old versions
# emerge -P gentoo-sources
In most cases, temporary files used during compilation will still remain under
the appropriate source directory under /usr/src. It is safe to
remove these using rm.
You can also safely delete any modules that were used by this kernel. This can
be done by removing the appropriate directories under /lib/modules/
that relate to the kernel versions you are removing. Be careful not to delete
modules belonging to kernels that you still use!
Finally, you can mount your /boot partition and remove the
bzImage file(s) for the kernel(s) you are pruning. You should also
edit your boot loader configuration so that it no longer references such
Advanced: Using your old kernel .config to configure a new one
It is sometimes possible to save time by re-using the configuration file from
your old kernel when configuring the new one. Note that this is generally
unsafe -- too many changes between every kernel release for this to be a
reliable upgrade path.
The only situation where this is appropriate is when upgrading from one Gentoo
kernel revision to another. For example, the changes made between
gentoo-sources-2.6.9-r1 and gentoo-sources-2.6.9-r2 will be very
small, so it is usually OK to use the following method. However, it is not
appropriate to use it in the example used throughout this document: upgrading
from 2.6.8 to 2.6.9. Too many changes between the official releases, and the
method described below does not display enough context to the user, often
resulting in the user running into problems because they disabled options that
they really didn't want to.
To reuse your old .config, you simply need to copy it over and
then run make oldconfig. In the following example, we take the
configuration from gentoo-sources-2.6.9-r1 and import it into
Code Listing 11.1: Reusing your old config
# cd /usr/src/linux-2.6.9-gentoo-r2
# cp ../linux-2.6.9-gentoo-r1/.config .
# make oldconfig
Code Listing 11.2: Reusing your old config with genkernel
# cd /etc/kernels
# cp kernel-config-x86-2.6.9-gentoo-r1 kernel-config-x86-2.6.9-gentoo-r2
# genkernel all
At this point, you may be asked to produce answers for configuration options
which have changed between the two versions. Once you have done that, you can
compile and install your kernel as normal, without having to go through the
menuconfig configuration process.
A much safer upgrading method is to copy your config as previously shown, and
then simply run make menuconfig. This avoids the problems of make
oldconfig mentioned previously, as make menuconfig will load up your
previous configuration as much as possible into the menu. Now all you have to
do is go through each option and look for new sections, removals, and so on. By
using menuconfig, you gain context for all the new changes, and can
easily view the new choices and review help screens much easier. You can even
use this for upgrades such as 2.6.8 to 2.6.9; just make sure you read through
the options carefully. Once you've finished, compile and install your kernel as
Problems after a kernel upgrade?
With the rapid development of the Linux kernel, it is inevitable that some
changes made from one kernel release to another may cause some problems. If you
have any issues with the latest versions of Gentoo-supported kernels then
please do report the issues to us.
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.