Man page - rpi-modcopy(1)

Packages contas this manual

Manual

RPI-MODCOPY(1) User Commands RPI-MODCOPY(1)

rpi-modcopy - selectively copy kernel modules and their dependencies

rpi-modcopy [OPTIONS] SOURCE DEST

rpi-modcopy copies a specified set of kernel modules, along with all their dependencies, from a source directory into a destination root filesystem. This is useful for building minimal Linux images that include only the kernel modules actually required.

The tool performs recursive dependency resolution: for each requested module, it identifies all dependent modules and includes them automatically. Built-in modules (compiled into the kernel itself) are recognised and handled safely.

Module aliases are supported in addition to literal module names. Common alias formats include:

  • Crypto aliases: crypto-xts(aes)
  • USB function aliases: usbfunc:ffs
  • Simple module names: dwc2, ipv6, fuse

Include the specified module (and its dependencies). May be specified multiple times. Can be a module name or a module alias.
Read module names from FILE, one per line. Lines beginning with # are treated as comments and ignored. Empty lines are ignored. If FILE is -, read from standard input.
May be specified multiple times. All sources are combined additively with any --module arguments.
Specify the kernel version string (e.g., 6.6.20+rpt-rpi-v8). Defaults to the currently running kernel as reported by uname -r.
Specify the module directory path relative to SOURCE. Defaults to /usr/lib/modules, which is correct for modern distributions including Raspberry Pi OS and Yocto-based systems. Use /lib/modules for traditional layouts.
Show what would be copied without actually copying anything. Implies --verbose.
Produce verbose output, showing dependency resolution and files being copied.
Continue processing even if some modules cannot be found. A warning is printed for each missing module. The exit status will be non-zero if any modules were skipped.
Display usage information and exit.

The SOURCE directory must contain kernel modules in the standard hierarchy:

SOURCE/<module-dir>/<kernel-version>/
├── kernel/
│   └── .../*.ko[.xz|.zst]
├── modules.builtin
├── modules.builtin.modinfo
└── modules.order

where <module-dir> is /usr/lib/modules by default, or as specified by --module-dir.

Kernel modules may be stored under lib/modules (traditional) or usr/lib/modules (modern distributions including Raspberry Pi OS, Yocto).

rpi-modcopy uses libkmod(3) directly for module lookup and dependency resolution, which handles both layouts seamlessly. The source directory is never modified.

The modules.builtin and modules.builtin.modinfo files must be present; they describe modules compiled directly into the kernel and are required for correct dependency resolution of built-in modules.

rpi-modcopy creates the following structure within DEST:

DEST/<module-dir>/<kernel-version>/
├── kernel/
│   └── <only requested modules + deps>
├── modules.alias
├── modules.alias.bin
├── modules.builtin
├── modules.builtin.modinfo
├── modules.dep
├── modules.dep.bin
├── modules.order
└── ...

The directory structure is created automatically. File permissions, ownership, timestamps, ACLs, and extended attributes are preserved from the source.

After copying, depmod(8) is run on the destination to generate the module dependency files (modules.dep, modules.alias, etc.) for the copied subset of modules.

The modules.order file is filtered to include only the modules that were actually copied. This ensures consistency with modprobe implementations that reference this file.

Note: Most modern systems use a lib -> usr/lib symbolic link at the root filesystem level. If your target system expects modules at /lib/modules but you are using the default --module-dir=/usr/lib/modules, ensure the destination contains this symlink. The symlink is not created by rpi-modcopy; it should be part of your base root filesystem setup.

In normal operation, rpi-modcopy produces no output on stdout.

With --verbose, the following is printed to stdout:

  • Each module being resolved and its dependencies
  • The list of files being copied
  • Summary statistics (number of modules copied, total size)

With --dry-run, the list of files that would be copied is printed to stdout, one per line.

Warnings and errors are printed to stderr, including:

  • Modules not found (fatal unless --keep-going is specified)
  • Missing or invalid source directory structure
  • Permission errors
  • Errors from depmod(8)

0
Success.
1
One or more modules could not be found (when using --keep-going).
2
Invalid arguments or usage error.
3
Source directory missing or invalid structure.
4
Destination directory not writable or other I/O error.
5
No modules specified (neither --module nor --module-file provided).

Copy the USB FunctionFS module for implementing USB gadgets:

rpi-modcopy --module=usbfunc:ffs /mnt/kernel-pkg /mnt/rootfs

Copy modules required for dm-crypt with AES-XTS encryption:

cat <<EOF | rpi-modcopy --module-file=- /mnt/kernel-pkg /mnt/rootfs
dm-crypt
algif_skcipher
crypto-xts(aes)
EOF

Copy modules for Adiantum encryption, suitable for devices without AES hardware acceleration:

rpi-modcopy --module=dm-crypt --module=crypto-nhpoly1305 \


    --module=crypto-xchacha12 --module=crypto-adiantum \


    /mnt/kernel-pkg /mnt/rootfs

Copy modules for a fastboot-style image with USB gadget and network support:

rpi-modcopy --module-file=gadget-modules.list --module=ipv6 --module=dwc2 \


    /mnt/kernel-pkg /mnt/rootfs

Given a file modules.list containing:

# USB gadget support
dwc2
usbfunc:ffs
# Networking
ipv6
# Filesystem
fuse

Copy all listed modules:

rpi-modcopy --module-file=modules.list /mnt/kernel-pkg /mnt/rootfs

For source directories using the traditional layout where modules are under lib/modules:

rpi-modcopy --module-dir=/lib/modules --module=dwc2 \


    /mnt/kernel-pkg /mnt/rootfs

Show what would be copied for a cryptroot setup:

rpi-modcopy --dry-run --module=dm-crypt --module=crypto-xtsæs \


    /mnt/kernel-pkg /mnt/rootfs

rpi-modcopy requires the following to be available:

  • depmod(8) — typically at /sbin/depmod, used to generate module dependency files at the destination.
  • libkmod(3) — the kmod library, used for module lookup and dependency resolution.

depmod(8), modinfo(8), modprobe(8), libkmod(3), uname(1)

Written for Raspberry Pi image building.

January 2026 rpi-modcopy