Debian ISO Non-Free Firmware Detection Explained

Starting with Debian 12 (Bookworm), the official Debian installation media natively includes non-free firmware binaries to automate hardware enablement during setup. This article explains how the Debian installer detects hardware components requiring proprietary blobs, automatically loads the required files to ensure functionality during installation, and persists these packages to the installed target system.

The Inclusion Policy Shift

Historically, the Debian project maintained a strict separation between completely free installation images and unofficial images that bundled proprietary firmware. Following a 2022 General Resolution, the project altered its policy. Official installation ISO images now bundle non-free firmware packages directly by default. These files reside in a dedicated archive component called non-free-firmware, keeping them distinct from general non-free software while making them readily accessible to the installer.

The Detection Mechanism (hw-detect)

The Debian Installer (d-i) handles hardware discovery primarily through the hw-detect package, which contains a dedicated subsystem named check-missing-firmware.

The detection process follows these operational steps:

  1. Kernel Driver Initialization: As the installer boots, the Linux kernel initializes drivers for detected PCI, USB, and other bus devices.
  2. Missing Firmware Triggers: When a driver encounters hardware that requires external microcode or firmware to function (such as Wi-Fi adapters, Ethernet controllers, or GPUs), the kernel issues an asynchronous request for the specific binary blob.
  3. Log Scanning: The check-missing-firmware script monitors the kernel ring buffer (dmesg) and /sys filesystem for notifications indicating that a driver requested a firmware file that was not immediately found in /lib/firmware.

Sourcing and Loading the Firmware

Once a missing firmware file is identified, the installer locates the appropriate payload:

  • Internal Media Search: The installer automatically searches the package pool contained on the booted ISO image. Most common firmware packages (such as firmware-linux-free, firmware-linux-nonfree, firmware-misc-nonfree, and vendor-specific packages for Intel, Realtek, Broadcom, and AMD) are pre-indexed on the image.
  • Removable Media Fallback: If the required firmware is not on the primary media, the installer prompts the user and scans external FAT, ext2/3/4, or ISO9660 partitions on plugged-in USB storage.
  • Dynamic Unpacking: Once the appropriate .deb package or raw firmware archive is located, the installer extracts the requested binaries directly into the installer runtime environment's /lib/firmware directory. It then reloads the associated kernel module or re-triggers the device subsystem to initialize the hardware immediately.

Target System Configuration and Persistence

Detecting and using firmware in the live installation environment is only the first step; the installer must also make the hardware functional upon reboot:

  1. Package Installation: When base system packages are installed onto the target drive, apt-install is invoked to permanently install the specific .deb packages containing the firmware utilized during the session.
  2. APT Source Configuration: The installer automatically adds the non-free-firmware component to /etc/apt/sources.list alongside main. This ensures that security updates and newer versions of the installed firmware packages are tracked during standard system upgrades.
  3. Initramfs Generation: Before the installation concludes, the update-initramfs hook executes within the target environment, ensuring any critical firmware required early in the boot sequence (such as CPU microcode or storage controller firmware) is packed into the boot image.

User Choice and Opt-Out Controls

Although non-free firmware detection is enabled by default to prevent failed network connections and broken display outputs, Debian retains options to disable it. Users can disable non-free firmware loading by entering expert install mode or by appending boot parameters such as firmware=never at the installer boot prompt. When disabled, the installer bypasses the automated check-missing-firmware routines and installs only strictly free software.