Load Linux Kernel Modules Safely with modprobe

You will finish with a repeatable way to inspect a kernel module, preview what modprobe would do, load it when appropriate, and remove it without guessing at dependencies. The examples match kmod 31, installed here as package version 31+20240202-2ubuntu7.2.

Allow about fifteen minutes. You need a shell and a module present under /lib/modules/$(uname -r). Reading configuration and running dry-runs is normally unprivileged. Loading or removing a module changes the running kernel and usually requires sudo.

1. Confirm the installed command and kernel

Start with read-only checks. This catches the common distraction where a command is being prepared for one kernel but modules are installed for another:

$ modprobe --version
kmod version 31
$ uname -r
6.8.0-139-generic
$ test -f "/lib/modules/$(uname -r)/modules.dep.bin" && echo dependency-index-present
dependency-index-present

modprobe looks in the module directory for the running kernel and expects the dependency index generated by depmod. If that index is missing or stale, repair the installed kernel package or run the distribution's normal depmod procedure before diagnosing a particular module.

2. Inspect the effective configuration

Configuration comes from modprobe.d files. The documented locations include /lib/modprobe.d, /usr/lib/modprobe.d, /usr/local/lib/modprobe.d, /run/modprobe.d and /etc/modprobe.d; files ending in .conf are read as configuration. Dump the effective result without changing anything:

$ modprobe -c | grep -E '^(alias|blacklist|options|softdep) ' | head -20
blacklist microcode
blacklist ath_pci
blacklist ohci1394

Your lines will differ. The useful configuration forms are options MODULE OPTION=VALUE, alias ALIAS MODULE, blacklist MODULE and softdep MODULE pre: OTHER post: OTHER. An alias gives a module another name. A blacklist suppresses a module's internal hardware aliases, rather than making every explicit modprobe MODULE fail. A soft dependency requests optional modules before or after the named module.

Do not add an option merely because its spelling looks plausible. Confirm the module parameter with the module documentation or modinfo. Treat install and remove rules as security-sensitive shell commands: they replace normal insertion or removal, and the manual warns that install is intended to be replaced by better dependency mechanisms over time.

3. Preview a module before loading it

Choose a module that exists on this host. bfq is a block I/O scheduler module here. The dry-run performs dependency and configuration processing but does not insert the module or run an install command:

$ modprobe --dry-run --verbose bfq
insmod /lib/modules/6.8.0-139-generic/kernel/block/bfq.ko.zst
$ printf 'exit status: %s\n' "$?"
exit status: 0

-n and --show are equivalent to --dry-run. Add -v when you need to see the planned command. This is a useful first test for a driver, but success only means that kmod could prepare the request. It does not prove that the kernel will accept the module.

To see the dependency set in the form commonly used when building an initramfs, use:

$ modprobe --show-depends bfq
insmod /lib/modules/6.8.0-139-generic/kernel/block/bfq.ko.zst

Install rules are displayed with an install prefix but are not run by --show-depends. If the module is already loaded, a normal insertion request usually succeeds and does nothing. Use --first-time when a script must distinguish an actual insertion from that no-op.

4. Load the module

Only after the dry-run looks correct should you make the live change. This needs elevated privileges:

$ sudo modprobe --verbose bfq
insmod /lib/modules/6.8.0-139-generic/kernel/block/bfq.ko.zst
$ lsmod | grep '^bfq '
bfq                    24576  0

The exact size and reference count vary. If the command fails, read the kernel message as well as kmod's error:

$ dmesg | tail -30

On systems where unprivileged users cannot read the kernel ring buffer, use the system journal or ask an administrator. A version-magic or symbol-version error means the module does not match this kernel. Do not jump straight to --force: --force-vermagic, --force-modversion and --force remove checks intended to protect the kernel.

5. Pass parameters deliberately

Arguments after the module name are passed to the kernel and are combined with options from configuration. Use the parameter documented for your exact module:

$ sudo modprobe MODULE_NAME OPTION_NAME=VALUE

Replace all three placeholder words before running the command. If the same module also has an options line in modprobe.d, the configured and command-line options are added together. Check the resulting module state with lsmod and inspect recognised parameters with modinfo MODULE_NAME.

6. Remove it, only when it is safe

Removal is usually unnecessary. It can fail when the module is busy, and removing a driver can disconnect hardware or a network. First preview it:

$ modprobe --remove --dry-run --verbose bfq
$ printf 'exit status: %s\n' "$?"
exit status: 0

If the module is not in use and you have a recovery path, remove it with elevated privileges:

$ sudo modprobe --remove bfq
$ lsmod | grep '^bfq '
$ printf 'grep status: %s\n' "$?"
grep status: 1

The final status of 1 from grep means no matching loaded module was found; it is not a modprobe failure. modprobe -r may also try to remove dependencies that are unused. If the module is busy, modprobe -r --wait=TIMEOUT_MSEC MODULE_NAME retries for the specified maximum time. Do not use a wait merely to force removal from a live service.

7. Recover from a configuration mistake

If a new .conf rule causes trouble, stop the affected service if possible, move or edit that rule through your normal change process, and re-run modprobe -c to confirm the effective configuration. Then use a dry-run before retrying. For a module that was loaded manually, sudo modprobe -r MODULE_NAME is the direct undo, provided the module is not needed by a running device or service.

Do not confuse an explicit module name with automatic hardware probing. modprobe --use-blacklist MODULE_NAME applies blacklist rules to the requested name as well, and is commonly used by udev. The default explicit request may still load a module that has been blacklisted for its internal aliases.