Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Linux kernel selftests, commonly called kselftest, are an in-tree collection of userspace programs, scripts, and supporting components under tools/testing/selftests/. They exercise a running kernel through system calls, devices, filesystems, networking, process behavior, security interfaces, and other observable features.
Kselftest is a framework of subsystem collections, not one universal compatibility test or a single binary. You normally build the tests, boot the kernel you intend to evaluate, and then run either selected collections or the full set. Results depend on the kernel commit, configuration, architecture, hardware, privileges, and userspace environment.
What Linux kernel selftests are
Kselftest provides regression and behavioral tests for kernel features from userspace. Collections cover areas such as system calls and ABI behavior, ptrace, timers, seccomp, BPF, memory management, filesystems, networking, scheduling, synchronization, namespaces, cgroups, signals, resource controls, architecture-specific behavior, and device or hotplug paths.
Recommended Free Tools
The available collections change with your checkout. Use the selftests Makefile and source directories as the authoritative list rather than relying on a static list in an article.
#1 Best Overall
“Selftest” does not mean the kernel tests itself without preparation. Most tests are ordinary userspace executables or shell scripts that interact with the already booted kernel. A test can therefore validate complete system behavior, but it cannot directly call arbitrary private kernel functions.
Kselftest versus KUnit and other tools
| Tool | Runs where | Best for | Limitation |
|---|---|---|---|
| kselftest | Mostly userspace | Syscalls, devices, filesystems, namespaces, security and whole-feature behavior | Needs a suitable running system; cannot directly inspect every internal function |
| KUnit | Inside the kernel | Small, isolated units and internal data structures | Not a substitute for multi-process or hardware-facing tests |
| Sanitizers and debugging | Instrumented kernel while tests run | Memory errors, races, locking bugs and undefined behavior | Adds overhead and often requires a special debug configuration |
| Static analysis | Source code | Type, API and source-level defects without booting | Cannot validate runtime behavior |
Use KUnit for an internal helper, kselftest for a userspace-visible interface, and instrumentation such as KASAN, KCSAN, KFENCE, UBSAN, lockdep, kmemleak, KCOV or gcov to expose defects while functional tests execute.
Prerequisites and a safe test environment
- A Linux kernel source tree, compiler and normal kernel build tools.
- Generated or prepared headers for that tree.
- Development libraries and userspace utilities required by the collections you select.
- A VM, lab machine or other host that can safely boot the kernel under test.
- Root or equivalent capabilities only for tests that require privileged operations.
- Recovery: a known-good boot entry, VM snapshot, serial console or out-of-band management.
Some tests alter namespaces, mounts, cgroups, devices, modules, network state or hotplug resources. Do not begin by running everything as root on a production server.
Build and run kselftest
From the kernel source tree, the basic build is:
make headers
make -C tools/testing/selftestsYou can build and run through the top-level target:
make kselftestFor a direct run of the built tests:
make -C tools/testing/selftests run_testsThe normal workflow is to build, install and boot the kernel you intend to test before executing tests. Preserve the complete console output and kernel logs; an aggregate status alone is not enough.
In CI, make partial builds fail explicitly:
make -C tools/testing/selftests FORCE_TARGETS=1Without FORCE_TARGETS=1, the build can appear successful when at least one requested target built while another target failed.
Run selected collections
Targeted runs are usually fastest during development:
make -C tools/testing/selftests TARGETS=ptrace run_tests
make TARGETS="size timers" kselftestSkip collections when a host cannot support them:
make -C tools/testing/selftests SKIP_TARGETS=ptrace run_tests
make SKIP_TARGETS="size timers" kselftestYou may combine an allowlist and skiplist:
make TARGETS="breakpoints size timers" SKIP_TARGETS=size kselftestKeep build artifacts outside the source tree with either form:
make O=/tmp/kselftest TARGETS="size timers" kselftest
export KBUILD_OUTPUT=/tmp/kselftest
make TARGETS="size timers" kselftestO= takes precedence over KBUILD_OUTPUT. Use summary=1 when you want a concise overview plus per-test output files:
make summary=1 kselftestInstall, package and run on another machine
Install the test tree in the default location or choose a destination:
Rank #3
make -C tools/testing/selftests install
make -C tools/testing/selftests install INSTALL_PATH=/some/other/pathThe installation contains run_kselftest.sh:
cd kselftest_install
./run_kselftest.sh -l
./run_kselftest.sh -c size -c seccomp
./run_kselftest.sh -t timers:posix_timers -t timer:nanosleep
./run_kselftest.sh -hTo transfer tests as an archive:
make -C tools/testing/selftests gen_tar
make -C tools/testing/selftests gen_tar FORMAT=.xz
make -C tools/testing/selftests gen_tar TARGETS="size" FORMAT=.xzPackages are placed below the installation path’s kselftest-packages directory. Packaging separates build and execution machines, but it does not remove runtime dependencies, required kernel configuration or hardware requirements.
Read results correctly
Interpret statuses as follows:
- Pass: assertions completed as expected under the current conditions.
- Fail: an assertion observed unexpected behavior or could not complete its required check.
- Skip: a prerequisite feature, configuration, architecture, hardware or privilege was unavailable.
- Error: the runner or test hit an execution or infrastructure problem.
- Timeout: the test exceeded its limit; this is not automatically a kernel defect.
The documented default timeout is 45 seconds per test, although tests may override it. The installed runner can override it for a run:
./run_kselftest.sh --override-timeout 165Machine load and system conditions affect duration, so investigate a timeout rather than treating it as proof of a regression. Record the kernel commit or release, .config, architecture and CPU, distribution and userspace versions, exact command, privilege level, loaded modules, hardware, full TAP output and kernel logs.
Privileges and hotplug safety
Network namespaces, mounts, filesystems, CPU or memory hotplug, BPF, tracing, cgroups, modules and device state can require root or special capabilities. Run unprivileged collections as an ordinary user where possible, and use a disposable VM or maintenance window for privileged work.
Hotplug tests deserve particular caution. The documentation warns that CPU and memory hotplug operations can wait indefinitely for resources to become offline. The normal path uses limited behavior; the broader target is:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Rank #4
- Used Book in Good Condition
make -C tools/testing/selftests hotplug
make -C tools/testing/selftests run_hotplugDo not run the full hotplug target first on a production host. Have console or out-of-band access and treat a hang as an operational incident before assuming a kernel bug.
Debug a failed selftest
- Capture the exact collection, test name and command.
- Check whether the result is a skip, missing prerequisite or infrastructure error.
- Read the individual output file and TAP diagnostics.
- Inspect
dmesg, tracing and audit logs. - Verify kernel configuration, architecture, hardware, virtualization and privileges.
- Rerun the smallest failing test, then compare with a known-good kernel.
- Compare the same commit with the relevant patch reverted or applied.
- Use an instrumented kernel when memory, race, locking or undefined behavior is suspected.
A mainline test checkout can sometimes run against an older stable kernel, and tests should skip gracefully when features are absent, but compatibility is collection-specific. Always compare commits and .config, not just release labels.
Write a new kselftest
Choose the test form
Use a normal userspace program or shell script when behavior is visible through a syscall, device, filesystem, process, namespace or similar interface. The supplied kselftest_harness.h supports structured userspace tests; seccomp BPF tests are useful examples.
If the test needs code or state inside the kernel, add a companion module using tools/testing/selftests/kselftest_module.h and tools/testing/selftests/kselftest/module.sh. A module-based test normally needs a module, a loader/unloader script, configuration, a collection Makefile entry, module installation and a run step.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →make kselftest-merge
make modules
sudo make modules_install
make TARGETS=lib kselftestEmit TAP-compatible output so automation can parse pass, fail, skip and diagnostics.
Common Makefile variables
TEST_PROGS: shell tests.TEST_GEN_PROGS: generated executables.TEST_CUSTOM_PROGS: tests with custom build rules.TEST_PROGS_EXTENDEDandTEST_GEN_PROGS_EXTENDED: helpers installed but not run by default.TEST_FILESandTEST_GEN_FILES: test data files.TEST_INCLUDES: dependencies needed when exporting or installing.KHDR_INCLUDES: preference for kernel-source headers.TARGETS,SKIP_TARGETSandFORCE_TARGETS: selection, exclusion and strict build behavior.
Use the common lib.mk facilities instead of inventing an unrelated build system. Add configuration only when the test genuinely needs a kernel feature, and make unsupported environments report a clear skip.
When kselftest is the right—and wrong—choice
Choose it for userspace-visible features, interactions across processes or subsystems, and regression tests that should run on multiple kernel versions or configurations. Kselftest alone is not exhaustive hardware compatibility testing, long-duration stress testing, fuzzing, performance proof or a substitute for an isolated internal unit test. Combine it with KUnit, sanitizers, coverage tools, fuzzers and static analysis as the defect requires.
Further reading
- Kernel 6.14 kselftest documentation
- Mainline kselftest guide
- Kernel testing overview
- Current selftest source tree
Frequently Asked Questions
Can I run kselftest without compiling a kernel?
You can build or install the tests separately, but meaningful results require a compatible running kernel and its configuration, features, hardware and userspace dependencies.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallDo all selftests require root?
No. Run non-privileged tests as a normal user; use root or specific capabilities only for collections that manipulate protected kernel or system state.
Why was a test skipped?
The required kernel configuration, feature, hardware, architecture, privilege or userspace dependency was unavailable. A skip is neither a pass nor proof of failure.
Can I run kselftest in a container?
Some collections work, but containers commonly lack namespaces, capabilities, debugfs, tracefs, devices or host-level control. Validate each collection and prefer a VM for privileged tests.
The Bottom Line
Kselftest is the Linux kernel’s practical, userspace-facing regression layer: build it, boot the kernel you mean to test, select collections deliberately, preserve TAP and kernel logs, and interpret skips, errors and timeouts separately from genuine failures.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
