Linux online course

Load Linux Kernel Modules with insmod and modprobe

Learn how Linux kernel modules work, how to load them with insmod and modprobe, inspect dependencies, use parameters, verify loading, troubleshoot errors, and configure boot-time loading.

A kernel module is a loadable piece of functionality that extends the running Linux kernel without rebuilding or rebooting the kernel. Modules are commonly used for hardware drivers, filesystems, networking features, and other optional kernel capabilities. They are also called loadable kernel modules or LKMs.

Linux and its device-management services often load required modules automatically. Manual loading is mainly useful when testing a driver or filesystem, temporarily enabling a feature, troubleshooting hardware, or supporting unusual hardware and storage requirements.

Installed modules are normally organized beneath /lib/modules/$(uname -r)/, where $(uname -r) expands to the release of the currently running kernel. For related filesystem concepts, see Linux file structure.

Check the Running Kernel and Module Availability

A module must be built for, and installed for, the kernel that is currently running. First identify that kernel:

uname -r

Use modinfo when you know the logical module name:

modinfo loop
modinfo -n loop

modinfo displays metadata for an installed module. The -n option prints the associated module filename. You can also search the module tree directly:

find /lib/modules/$(uname -r) -type f -name 'loop.ko*'

A module filename commonly ends in .ko. Distribution packages may compress module files, producing names such as .ko.xz, .ko.gz, or .ko.zst. The filename is not the same thing as the logical module name supplied to modprobe: normally omit the directory and .ko suffix when using modprobe.

Load a Module with insmod

insmod is a low-level insertion command. It accepts an explicit path to a module file:

sudo insmod /path/to/module.ko

Root privileges are normally required because inserting kernel code changes the running kernel. A module can accept parameters as additional arguments:

sudo insmod /path/to/module.ko parameter=value

The parameter must actually be supported by that module. Discover supported parameters with modinfo -p MODULE_NAME.

insmod does not automatically resolve or load prerequisite modules. Consequently, insertion can fail even when the target file exists. It is most useful for direct testing or controlled, low-level workflows. Routine administration normally uses modprobe.

For example, you can obtain a path and pass it to insmod:

module_path=$(modinfo -n loop)
sudo insmod "$module_path"

This is not a useful normal workflow if loop is already loaded, and it can fail if required dependencies are not loaded. Module-management tools and distributions may also handle compressed module files differently, so prefer modprobe for installed modules.

Load a Module with modprobe

modprobe is the usual command for loading installed modules. It takes a logical module name, not a path:

sudo modprobe loop

It consults dependency metadata and modprobe configuration, then loads prerequisite modules before loading the requested module. Dependency information is maintained in files such as modules.dep. The depmod command generates or refreshes this metadata.

Module names commonly use underscores, while command-line forms often accept hyphens as equivalent. For example, a module named example_module may also be addressed as example-module. Use the name reported by modinfo when there is uncertainty.

The relationship is:

• insmod receives a file path and attempts direct insertion.
• modprobe receives a module name, reads dependency and configuration metadata, and performs the required insertion actions.

Inspect Module Metadata and Dependencies

Module metadata describes the code and how it can be used:

modinfo MODULE_NAME
modinfo -p MODULE_NAME
modinfo -n MODULE_NAME

Depending on the module, modinfo can show its filename, description, license, aliases, parameters, kernel-version information, and declared dependencies. The -p option lists supported parameters.

To see the dependency-related actions that modprobe would process, use:

modprobe --show-depends overlay

This output helps explain which prerequisite modules are needed and can reveal why a module cannot be loaded. It is especially useful when comparing a direct insmod attempt with dependency-aware loading.

Use Dry-Run and Verbose Modes

A dry run simulates module handling without changing the running kernel. The -n or --dry-run option performs resolution checks without inserting modules. The -v or --verbose option displays actions taken or planned.

sudo modprobe -n -v overlay

Combining these options is a safe way to preview dependency resolution and the commands that would be used. The exact output varies by distribution and module state. --show-depends focuses on dependency actions and is useful alongside the dry run.

Verify That a Module Is Loaded

Use lsmod to list modules currently loaded into the kernel:

lsmod
lsmod | grep '^loop'

For a shell pipeline that remains successful when no match is found:

lsmod | grep '^loop' || true

The kernel exposes equivalent module state through /proc/modules:

cat /proc/modules

A successful modprobe command confirms that insertion did not report an error, but it does not prove that the expected feature works. Also verify the related device, filesystem mount, network interface, service, or application. A driver may load successfully without binding to any hardware.

Module Parameters

A module parameter is a module-specific setting supplied when the module is loaded. Names and accepted values vary by module and kernel version. Discover parameters before using them:

modinfo -p MODULE_NAME

Supply a temporary option with modprobe:

sudo modprobe MODULE_NAME parameter=value

Or pass it to insmod when inserting a file directly:

sudo insmod /path/to/MODULE_NAME.ko parameter=value

Do not assume that an illustrative name such as example_module or option_name exists on every system. Replace it with a module and parameter reported by modinfo -p. Parameters supplied on the command line are temporary: they apply to that load and normally disappear after reboot or removal.

Remove Modules Safely

Use dependency-aware removal for normal administration:

sudo modprobe -r loop
lsmod | grep '^loop' || true

modprobe -r removes the requested module and attempts to remove dependencies that are no longer needed. The lower-level alternative is:

sudo rmmod MODULE_NAME

A module cannot be removed while it is in active use, referenced by another loaded module, or marked non-unloadable. It may support a mounted filesystem, device, network interface, or service. Stop dependent services and safely detach consumers before trying again. Removing a driver can interrupt hardware access, so do not remove one from a feature that must remain available.

Load Modules Automatically at Boot

Manually loaded modules normally remain loaded only until reboot. On systems using systemd, place one module name per line in a file under /etc/modules-load.d/:

printf '%s\n' 'example_module' | sudo tee /etc/modules-load.d/example_module.conf

To persist options whenever modprobe loads the module, create a file under /etc/modprobe.d/:

printf '%s\n' 'options example_module option_name=option_value' | sudo tee /etc/modprobe.d/example_module.conf

Use actual module and parameter names from modinfo. Some distributions provide additional legacy or distribution-specific startup mechanisms. Follow the active distribution's documented method rather than adding multiple competing configurations.

Test persistence without immediately rebooting by loading the module manually, checking the configuration syntax and file contents, and reviewing kernel or service logs. A reboot or restart of the distribution's module-loading service can provide final validation when appropriate; test on systems where interrupting the feature is safe.

Module Loading Policy and Safety

Loading kernel code affects the running kernel and requires administrative privileges. Use only trusted, compatible modules from appropriate distribution packages or a controlled build process. A faulty or malicious module can crash the system, expose data, or compromise the kernel.

Secure Boot, kernel lockdown, and module signature enforcement can reject unsigned or untrusted modules. Review the system policy before installing an external driver. If a module should not be selected automatically, a modprobe blacklist rule can help:

printf '%s\n' 'blacklist MODULE_NAME' | sudo tee /etc/modprobe.d/blacklist-MODULE_NAME.conf

Blacklisting generally prevents automatic alias-based loading; it does not necessarily prevent every explicit loading method or every distribution-specific early-boot mechanism. Review the complete boot and driver configuration when a module continues to appear.

Troubleshoot Failed Module Loads

Start with the active kernel, module metadata, dependency plan, and kernel messages:

uname -r
modinfo MODULE_NAME
sudo modprobe -n -v MODULE_NAME
sudo modprobe MODULE_NAME
dmesg | tail -n 50
journalctl -k -n 50 --no-pager

dmesg reads the kernel message buffer. journalctl -k queries kernel messages stored by the system journal. These messages often contain the specific reason hidden behind a short command-line error.

Common Command Reference

For broader command-line practice, see Linux command-line topics and show the full path of shell commands.