Extract and Inspect an Initramfs with unmkinitramfs

When a box will not boot past early userspace, unmkinitramfs unpacks the initramfs so you can see what is actually inside it. It extracts into a directory you choose and never touches the original image in /boot, which makes it useful for checking modules, firmware, hooks or boot scripts that might be involved in an early-boot failure.

• Time: about ten minutes for a normal image, plus time and disk space for the extracted files.
• You need: a shell, enough free space for an extracted image, and read access to the image. Extraction itself normally needs no elevated privileges if the destination is writable by you.
• Version used here: initramfs-tools-core 0.142ubuntu25.8.

1. Check the installed command

Start with the local help and package version. These are ordinary read-only commands:

$ command -v unmkinitramfs
/usr/bin/unmkinitramfs
$ dpkg-query -W -f='${Package} ${Version}\n' initramfs-tools-core
initramfs-tools-core 0.142ubuntu25.8
$ unmkinitramfs -h

Usage: unmkinitramfs [-v] initramfs-file directory

Options:
  -v   Display verbose messages about extraction

The syntax takes two positional arguments: the input initramfs and the output directory. -v is optional and prints names as files are extracted. The short help is the most reliable description of the binary actually installed on your machine, since package versions can differ.

2. Choose the image and a disposable destination

List the available images before choosing one. This first command only reads directory metadata:

$ ls -lh /boot/initrd.img*
lrwxrwxrwx 1 root root  28 ... /boot/initrd.img -> initrd.img-6.8.0-142-generic
-rw-r--r-- 1 root root  73M ... /boot/initrd.img-6.8.0-139-generic
-rw-r--r-- 1 root root  73M ... /boot/initrd.img-6.8.0-142-generic

A pathname ending in /boot/initrd.img may be a symbolic link to the image currently selected. For a repeatable investigation, use the versioned file explicitly. Replace 6.8.0-142-generic below with a filename that actually exists on your host:

$ IMAGE=/boot/initrd.img-6.8.0-142-generic
$ DEST=/tmp/initramfs-6.8.0-142-generic
$ test -r "$IMAGE" && printf 'input is readable: %s\n' "$IMAGE"
input is readable: /boot/initrd.img-6.8.0-142-generic

Choose a destination that does not already hold files you care about. The program creates the directory when needed, but it does not make an existing destination disposable. If DEST points at a shared or privileged directory, stop and pick another path.

3. Extract without changing the boot image

Run the extraction as your normal user:

$ unmkinitramfs "$IMAGE" "$DEST"
$ printf 'exit status: %s\n' "$?"
exit status: 0

An exit status of zero means the extraction pipeline completed. It does not mean every file is meaningful for your kernel problem, so inspect the result before drawing a conclusion. A non-zero status means the extraction did not finish cleanly: check the input path, destination permissions, free space and the command's diagnostic text.

$ test -d "$DEST" && find "$DEST" -mindepth 1 -maxdepth 1 -printf '%f\n' | sort
early
early2
early3
main

The exact list depends on the image. A simple compressed image may extract directly into the destination. The current Ubuntu script also separates an uncompressed prepended cpio archive into directories such as early, early2 and early3, then places the regular compressed archive under main.

That is installed-script behaviour, not a promise that every older package uses the same layout. The manpage describes the image as potentially containing multiple segments passed to cpio in order, and it records limitations for more complex multi-segment images.

4. Inspect the files that matter

Start with a shallow listing, then narrow the search to the actual question you are investigating:

$ find "$DEST" -maxdepth 3 -printf '%y %p\n' | sort | head -40
$ find "$DEST" -type f \( -name '*.ko' -o -name '*.conf' -o -name '*.sh' \) -print | head -40
$ find "$DEST" -type f -path '*/etc/*' -print | sort | head -40

Do not assume every path lives in main: firmware or early CPU microcode may sit in one of the early directories, while the normal initramfs tree is under main. Compare paths and file contents with the kernel version you selected. A file being present in an image is evidence of inclusion, not proof the kernel will load it or that a boot hook will use it.

For a quick read-only content check, use standard tools against the extracted copy:

$ test -f "$DEST/main/init" && sed -n '1,40p' "$DEST/main/init"
$ find "$DEST" -type f -name '*.ko' -print | wc -l
42

Exact files and counts vary by host. Do not run scripts from the extracted tree. An initramfs holds boot-time programs and configuration, but extraction does not make those files safe to execute as ordinary user commands.

5. Use verbose mode when the layout is unclear

When you need to see exactly what the command sends through extraction, repeat the operation into a second, empty destination with -v:

$ VERBOSE_DEST=/tmp/initramfs-verbose
$ unmkinitramfs -v "$IMAGE" "$VERBOSE_DEST" | head -30
.
kernel
kernel/x86
kernel/x86/microcode
kernel/x86/microcode/AuthenticAMD.bin

Verbose output can be very large. Piping it to head may close the pipe early and make the shell report status 141, even though the beginning shown is still useful. For a complete log, redirect to a temporary file instead:

$ unmkinitramfs -v "$IMAGE" "$VERBOSE_DEST" >/tmp/unmkinitramfs-files.txt
$ sed -n '1,30p' /tmp/unmkinitramfs-files.txt

This second extraction uses more disk space. Do not start it if the first output already fills the filesystem.

6. Remove only the disposable copies

After inspection, check the target before deleting it. Removal is destructive, and the extracted files are not recoverable from the command itself:

$ printf 'about to remove: %s\n' "$DEST"
about to remove: /tmp/initramfs-6.8.0-142-generic
$ test "$DEST" = /tmp/initramfs-6.8.0-142-generic
$ rm -rf -- "$DEST"
$ test ! -e "$DEST" && printf 'extracted copy removed\n'
extracted copy removed

Only remove the explicit temporary destination you chose. If you need the evidence later, copy selected files to a documented case directory before cleanup. The original /boot/initrd.img-... file is untouched by extraction or by removing the destination.