How to quickly build a trimmed Linux kernel

This guide explains how to swiftly build Linux kernels that are ideal for testing purposes, but perfectly fine for day-to-day use, too.

The essence of the process (aka ‘TL;DR’)

[If you are new to compiling Linux, ignore this TLDR and head over to the next section below: it contains a step-by-step guide, which is more detailed, but still brief and easy to follow; that guide and its accompanying reference section also mention alternatives, pitfalls, and additional aspects, all of which might be relevant for you.]

If your system uses techniques like Secure Boot, prepare it to permit starting self-compiled Linux kernels; install compilers and everything else needed for building Linux; make sure to have 12 Gigabyte free space in your home directory. Now run the following commands to download fresh Linux mainline sources, which you then use to configure, build and install your own kernel:

git clone --depth 1 -b master \
  https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git ~/linux/
cd ~/linux/
# Hint: if you want to apply patches, do it at this point. See below for details.
# Hint: it's recommended to tag your build at this point. See below for details.
yes "" | make localmodconfig
# Hint: at this point you might want to adjust the build configuration; you'll
#   have to, if you are running Debian. See below for details.
make -j $(nproc --all)
# Note: on many commodity distributions the next command suffices, but on Arch
#   Linux, its derivatives, and some others it does not. See below for details.
command -v installkernel && sudo make modules_install install
reboot

If you later want to build a newer mainline snapshot, use these commands:

cd ~/linux/
git fetch --depth 1 origin
# Note: the next command will discard any changes you did to the code:
git checkout --force --detach origin/master
# Reminder: if you want to (re)apply patches, do it at this point.
# Reminder: you might want to add or modify a build tag at this point.
make olddefconfig
make -j $(nproc --all)
# Reminder: the next command on some distributions does not suffice.
command -v installkernel && sudo make modules_install install
reboot

Step-by-step guide

Compiling your own Linux kernel is easy in principle. There are various ways to do it. Which of them actually work and is the best depends on the circumstances.

This guide describes a way perfectly suited for those who want to quickly install Linux from sources without being bothered by complicated details; the goal is to cover everything typically needed on mainstream Linux distributions running on commodity PC or server hardware.

The described approach is great for testing purposes, for example to try a proposed fix or to check if a problem was already fixed in the latest codebase. Nonetheless, kernels built this way are also totally fine for day-to-day use while at the same time being easy to keep up to date.

The following steps describe the important aspects of the process; a comprehensive reference section later explains each of them in more detail. It sometimes also describes alternative approaches, pitfalls, as well as errors that might occur at a particular point — and how to then get things rolling again.

::: {#backup_sbs}

Create a fresh backup and put system repair and restore tools at hand, just to be prepared for the unlikely case of something going sideways.

[details<backup>{.interpreted-text role=“ref”}] :::

::: {#secureboot_sbs}

On platforms with ‘Secure Boot’ or similar techniques, prepare everything to ensure the system will permit your self-compiled kernel to boot later. The quickest and easiest way to achieve this on commodity x86 systems is to disable such techniques in the BIOS setup utility; alternatively, remove their restrictions through a process initiated by mokutil --disable-validation.

[details<secureboot>{.interpreted-text role=“ref”}] :::

::: {#buildrequires_sbs}

Install all software required to build a Linux kernel. Often you will need: ‘bc’, ‘binutils’ (‘ld’ et al.), ‘bison’, ‘flex’, ‘gcc’, ‘git’, ‘openssl’, ‘pahole’, ‘perl’, and the development headers for ‘libelf’ and ‘openssl’. The reference section shows how to quickly install those on various popular Linux distributions.

[details<buildrequires>{.interpreted-text role=“ref”}] :::

::: {#diskspace_sbs}

Ensure to have enough free space for building and installing Linux. For the latter 150 Megabyte in /lib/ and 100 in /boot/ are a safe bet. For storing sources and build artifacts 12 Gigabyte in your home directory should typically suffice. If you have less available, be sure to check the reference section for the step that explains adjusting your kernels build configuration: it mentions a trick that reduce the amount of required space in /home/ to around 4 Gigabyte.

[details<diskspace>{.interpreted-text role=“ref”}] :::

::: {#sources_sbs}

Retrieve the sources of the Linux version you intend to build; then change into the directory holding them, as all further commands in this guide are meant to be executed from there.

[Note: the following paragraphs describe how to retrieve the sources by partially cloning the Linux stable git repository. This is called a shallow clone. The reference section explains two alternatives: packaged archives<sources_archive>{.interpreted-text role=“ref”} and a full git clone<sources_full>{.interpreted-text role=“ref”} ; prefer the latter, if downloading a lot of data does not bother you, as that will avoid some peculiar characteristics of shallow clones the reference section explains<sources_shallow>{.interpreted-text role=“ref”} .]

First, execute the following command to retrieve a fresh mainline codebase:
git clone --no-checkout --depth 1 -b master \
  https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git ~/linux/
cd ~/linux/
If you want to access recent mainline releases and pre-releases, deepen you clone’s history to the oldest mainline version you are interested in:
git fetch --shallow-exclude=v6.0 origin
In case you want to access a stable/longterm release (say v6.1.5), simply add the branch holding that series; afterwards fetch the history at least up to the mainline version that started the series (v6.1):
git remote set-branches --add origin linux-6.1.y
git fetch --shallow-exclude=v6.0 origin
Now checkout the code you are interested in. If you just performed the initial clone, you will be able to check out a fresh mainline codebase, which is ideal for checking whether developers already fixed an issue:
git checkout --detach origin/master
If you deepened your clone, you instead of origin/master can specify the version you deepened to (v6.0 above); later releases like v6.1 and pre-release like v6.2-rc1 will work, too. Stable or longterm versions like v6.1.5 work just the same, if you added the appropriate stable/longterm branch as described.

[details<sources>{.interpreted-text role=“ref”}] :::

::: {#patching_sbs}

In case you want to apply a kernel patch, do so now. Often a command like this will do the trick:
patch -p1 < ../proposed-fix.patch
If the -p1 is actually needed, depends on how the patch was created; in case it does not apply thus try without it.

If you cloned the sources with git and anything goes sideways, run git reset --hard to undo any changes to the sources.

[details<patching>{.interpreted-text role=“ref”}] :::

::: {#tagging_sbs}

If you patched your kernel or have one of the same version installed already, better add a unique tag to the one you are about to build:
echo "-proposed_fix" > localversion
Running uname -r under your kernel later will then print something like ‘6.1-rc4-proposed_fix’.

[details<tagging>{.interpreted-text role=“ref”}]
::: {#configuration_sbs}
Create the build configuration for your kernel based on an existing configuration.

If you already prepared such a ‘.config’ file yourself, copy it to ~/linux/ and run make olddefconfig.

Use the same command, if your distribution or somebody else already tailored your running kernel to your or your hardware’s needs: the make target ‘olddefconfig’ will then try to use that kernel’s .config as base.

Using this make target is fine for everybody else, too — but you often can save a lot of time by using this command instead:
yes "" | make localmodconfig
This will try to pick your distribution’s kernel as base, but then disable modules for any features apparently superfluous for your setup. This will reduce the compile time enormously, especially if you are running an universal kernel from a commodity Linux distribution.

There is a catch: ‘localmodconfig’ is likely to disable kernel features you did not use since you booted your Linux — like drivers for currently disconnected peripherals or a virtualization software not haven’t used yet. You can reduce or nearly eliminate that risk with tricks the reference section outlines; but when building a kernel just for quick testing purposes it is often negligible if such features are missing. But you should keep that aspect in mind when using a kernel built with this make target, as it might be the reason why something you only use occasionally stopped working.

[details<configuration>{.interpreted-text role=“ref”}] ::: :::

::: {#configmods_sbs}

Check if you might want to or have to adjust some kernel configuration options:

Evaluate how you want to handle debug symbols. Enable them, if you later might need to decode a stack trace found for example in a ‘panic’, ‘Oops’, ‘warning’, or ‘BUG’; on the other hand disable them, if you are short on storage space or prefer a smaller kernel binary. See the reference section for details on how to do either. If neither applies, it will likely be fine to simply not bother with this. [details<configmods_debugsymbols>{.interpreted-text role=“ref”}]

Are you running Debian? Then to avoid known problems by performing additional adjustments explained in the reference section. [details<configmods_distros>{.interpreted-text role=“ref”}].

If you want to influence the other aspects of the configuration, do so now by using make targets like ‘menuconfig’ or ‘xconfig’. [details<configmods_individual>{.interpreted-text role=“ref”}]. :::

::: {#build_sbs}

Build the image and the modules of your kernel:
make -j $(nproc --all)
If you want your kernel packaged up as deb, rpm, or tar file, see the reference section for alternatives.

[details<build>{.interpreted-text role=“ref”}] :::

::: {#install_sbs}

Now install your kernel:
command -v installkernel && sudo make modules_install install
Often all left for you to do afterwards is a reboot, as many commodity Linux distributions will then create an initramfs (also known as initrd) and an entry for your kernel in your bootloader’s configuration; but on some distributions you have to take care of these two steps manually for reasons the reference section explains.

On a few distributions like Arch Linux and its derivatives the above command does nothing at all; in that case you have to manually install your kernel, as outlined in the reference section.

If you are running a immutable Linux distribution, check its documentation and the web to find out how to install your own kernel there.

[details<install>{.interpreted-text role=“ref”}] :::

::: {#another_sbs}

To later build another kernel you need similar steps, but sometimes slightly different commands.

First, switch back into the sources tree:
cd ~/linux/
In case you want to build a version from a stable/longterm series you have not used yet (say 6.2.y), tell git to track it:
git remote set-branches --add origin linux-6.2.y
Now fetch the latest upstream changes; you again need to specify the earliest version you care about, as git otherwise might retrieve the entire commit history:
git fetch --shallow-exclude=v6.0 origin
Now switch to the version you are interested in — but be aware the command used here will discard any modifications you performed, as they would conflict with the sources you want to checkout:
git checkout --force --detach origin/master
At this point you might want to patch the sources again or set/modify a build tag, as explained earlier. Afterwards adjust the build configuration to the new codebase using olddefconfig, which will now adjust the configuration file you prepared earlier using localmodconfig (~/linux/.config) for your next kernel:
# reminder: if you want to apply patches, do it at this point
# reminder: you might want to update your build tag at this point
make olddefconfig
Now build your kernel:
make -j $(nproc --all)
Afterwards install the kernel as outlined above:
command -v installkernel && sudo make modules_install install
[details<another>{.interpreted-text role=“ref”}] :::

::: {#uninstall_sbs}

Your kernel is easy to remove later, as its parts are only stored in two places and clearly identifiable by the kernel’s release name. Just ensure to not delete the kernel you are running, as that might render your system unbootable.

Start by deleting the directory holding your kernel’s modules, which is named after its release name — ‘6.0.1-foobar’ in the following example:
sudo rm -rf /lib/modules/6.0.1-foobar
Now try the following command, which on some distributions will delete all other kernel files installed while also removing the kernel’s entry from the bootloader configuration:
command -v kernel-install && sudo kernel-install -v remove 6.0.1-foobar
If that command does not output anything or fails, see the reference section; do the same if any files named ‘*6.0.1-foobar*’ remain in /boot/.

[details<uninstall>{.interpreted-text role=“ref”}] :::

::: {#submit_improvements} Did you run into trouble following any of the above steps that is not cleared up by the reference section below? Or do you have ideas how to improve the text? Then please take a moment of your time and let the maintainer of this document know by email (Thorsten Leemhuis <linux@leemhuis.info>), ideally while CCing the Linux docs mailing list (linux-doc@vger.kernel.org). Such feedback is vital to improve this document further, which is in everybody’s interest, as it will enable more people to master the task described here. :::

Reference section for the step-by-step guide

This section holds additional information for each of the steps in the above guide.

Prepare for emergencies {#backup}

Create a fresh backup and put system repair and restore tools at hand [... <backup_sbs>{.interpreted-text role=“ref”}]

Remember, you are dealing with computers, which sometimes do unexpected things — especially if you fiddle with crucial parts like the kernel of an operating system. That’s what you are about to do in this process. Hence, better prepare for something going sideways, even if that should not happen.

[back to step-by-step guide <backup_sbs>{.interpreted-text role=“ref”}]

Dealing with techniques like Secure Boot {#secureboot}

On platforms with ‘Secure Boot’ or similar techniques, prepare everything to ensure the system will permit your self-compiled kernel to boot later. [... <secureboot_sbs>{.interpreted-text role=“ref”}]

Many modern systems allow only certain operating systems to start; they thus by default will reject booting self-compiled kernels.

You ideally deal with this by making your platform trust your self-built kernels with the help of a certificate and signing. How to do that is not described here, as it requires various steps that would take the text too far away from its purpose; ‘Documentation/admin-guide/module-signing.rst’ and various web sides already explain this in more detail.

Temporarily disabling solutions like Secure Boot is another way to make your own Linux boot. On commodity x86 systems it is possible to do this in the BIOS Setup utility; the steps to do so are not described here, as they greatly vary between machines.

On mainstream x86 Linux distributions there is a third and universal option: disable all Secure Boot restrictions for your Linux environment. You can initiate this process by running mokutil --disable-validation; this will tell you to create a one-time password, which is safe to write down. Now restart; right after your BIOS performed all self-tests the bootloader Shim will show a blue box with a message ‘Press any key to perform MOK management’. Hit some key before the countdown exposes. This will open a menu and choose ‘Change Secure Boot state’ there. Shim’s ‘MokManager’ will now ask you to enter three randomly chosen characters from the one-time password specified earlier. Once you provided them, confirm that you really want to disable the validation. Afterwards, permit MokManager to reboot the machine.

[back to step-by-step guide <secureboot_sbs>{.interpreted-text role=“ref”}]

Install build requirements {#buildrequires}

Install all software required to build a Linux kernel. [...<buildrequires_sbs>{.interpreted-text role=“ref”}]

The kernel is pretty stand-alone, but besides tools like the compiler you will sometimes need a few libraries to build one. How to install everything needed depends on your Linux distribution and the configuration of the kernel you are about to build.

Here are a few examples what you typically need on some mainstream distributions:

Debian, Ubuntu, and derivatives:

sudo apt install bc binutils bison dwarves flex gcc git make openssl \
  pahole perl-base libssl-dev libelf-dev

Fedora and derivatives:

sudo dnf install binutils /usr/include/{libelf.h,openssl/pkcs7.h} \
  /usr/bin/{bc,bison,flex,gcc,git,openssl,make,perl,pahole}

openSUSE and derivatives:

sudo zypper install bc binutils bison dwarves flex gcc git make perl-base \
  openssl openssl-devel libelf-dev

In case you wonder why these lists include openssl and its development headers: they are needed for the Secure Boot support, which many distributions enable in their kernel configuration for x86 machines.

Sometimes you will need tools for compression formats like bzip2, gzip, lz4, lzma, lzo, xz, or zstd as well.

You might need additional libraries and their development headers in case you perform tasks not covered in this guide. For example, zlib will be needed when building kernel tools from the tools/ directory; adjusting the build configuration with make targets like ‘menuconfig’ or ‘xconfig’ will require development headers for ncurses or Qt5.

[back to step-by-step guide <buildrequires_sbs>{.interpreted-text role=“ref”}]

Space requirements {#diskspace}

Ensure to have enough free space for building and installing Linux. [... <diskspace_sbs>{.interpreted-text role=“ref”}]

The numbers mentioned are rough estimates with a big extra charge to be on the safe side, so often you will need less.

If you have space constraints, remember to read the reference section when you reach the section about configuration adjustments' <configmods>{.interpreted-text role=“ref”}, as ensuring debug symbols are disabled will reduce the consumed disk space by quite a few gigabytes.

[back to step-by-step guide <diskspace_sbs>{.interpreted-text role=“ref”}]

Download the sources {#sources}

Retrieve the sources of the Linux version you intend to build. [...<sources_sbs>{.interpreted-text role=“ref”}]

The step-by-step guide outlines how to retrieve Linux’ sources using a shallow git clone. There is more to tell about this method<sources_shallow>{.interpreted-text role=“ref”} and two alternate ways worth describing: packaged archives<sources_archive>{.interpreted-text role=“ref”} and a full git clone<sources_full>{.interpreted-text role=“ref”}. And the aspects ‘wouldn't it be wiser to use a proper pre-release than the latest mainline code <sources_snapshot>{.interpreted-text role=“ref”}’ and ‘how to get an even fresher mainline codebase <sources_fresher>{.interpreted-text role=“ref”}’ need elaboration, too.

Note, to keep things simple the commands used in this guide store the build artifacts in the source tree. If you prefer to separate them, simply add something like O=~/linux-builddir/ to all make calls; also adjust the path in all commands that add files or modify any generated (like your ‘.config’).

[back to step-by-step guide <sources_sbs>{.interpreted-text role=“ref”}]

Noteworthy characteristics of shallow clones {#sources_shallow}

The step-by-step guide uses a shallow clone, as it is the best solution for most of this document’s target audience. There are a few aspects of this approach worth mentioning:

This document in most places uses git fetch with --shallow-exclude= to specify the earliest version you care about (or to be precise: its git tag). You alternatively can use the parameter --shallow-since= to specify an absolute (say '2023-07-15') or relative ('12 months') date to define the depth of the history you want to download. As a second alternative, you can also specify a certain depth explicitly with a parameter like --depth=1, unless you add branches for stable/longterm kernels.

When running git fetch, remember to always specify the oldest version, the time you care about, or an explicit depth as shown in the step-by-step guide. Otherwise you will risk downloading nearly the entire git history, which will consume quite a bit of time and bandwidth while also stressing the servers.

Note, you do not have to use the same version or date all the time. But when you change it over time, git will deepen or flatten the history to the specified point. That allows you to retrieve versions you initially thought you did not need — or it will discard the sources of older versions, for example in case you want to free up some disk space. The latter will happen automatically when using --shallow-since= or --depth=.

Be warned, when deepening your clone you might encounter an error like ‘fatal: error in object: unshallow cafecaca0c0dacafecaca0c0dacafecaca0c0da’. In that case run git repack -d and try again“

In case you want to revert changes from a certain version (say Linux 6.3) or perform a bisection (v6.2..v6.3), better tell git fetch to retrieve objects up to three versions earlier (e.g. 6.0): git describe will then be able to describe most commits just like it would in a full git clone.