uc-tool

Generate AMD/Intel CPU microcode CPIO images from system firmware and optionally inject them into a live initrd, strip them out, or list initrd content.

Designed for use with antiX Linux and MX Linux live toolset: live-usb-maker, mx-snapshot/iso-snapshot, live-remaster, live-kernel-updater, and build-iso. Works standalone on any Debian/Ubuntu system.

What it does

Mode	Command
Generate microcode images + update initrd	uc-tool -i /boot/initrd.img
Generate images only, save to dir	uc-tool -d /tmp/ucode
Auto-detect initrd and dir from boot mode	uc-tool -D
Update initrd, keep the .img files	uc-tool -i /boot/initrd.img -k
Use firmware from a squashfs image	uc-tool -F /path/to/linuxfs -i initrd.gz
Strip microcode from initrd (no replacement)	uc-tool -S -i /boot/initrd.img
Check whether initrd contains microcode	uc-tool -H -i /boot/initrd.img
List ucode CPIOs (no writes)	uc-tool -l -i /boot/initrd.img
List all sections with sizes and compression	uc-tool -l all -i /boot/initrd.img
List all sections + files inside each	uc-tool -l unpack -i /boot/initrd.img
Extract ucode CPIOs only	uc-tool -x -d /tmp/out -i /boot/initrd.img
Extract all sections as raw files	uc-tool --extract=all -d /tmp/out -i /boot/initrd.img
Extract all sections + unpack each	uc-tool --extract=unpack -d /tmp/out -i /boot/initrd.img
Repack sections back into initrd	uc-tool --repack=/tmp/out -i /boot/initrd.img

When updating an initrd the tool:

• strips any existing microcode CPIOs from the head of the initrd
• prepends the freshly generated ones
• refreshes the .md5 sidecar file if present
• runs e4defrag if the target is on ext4
• verifies write integrity before removing the backup

Dependencies

Package	Purpose
cpio, coreutils, findutils	required
iucode-tool	required for Intel microcode
mount	required only when -F points to a squashfs file

Installation

From the .deb (recommended):

sudo dpkg -i uc-tool_*.deb

Manually:

sudo install -m 0755 uc-tool /usr/bin/uc-tool

Usage

Usage:  uc-tool [options]

  -u  --ucode=<list>       Vendors to build: amd, intel, or amd,intel
                           [default: amd,intel]
  -d  --directory=<dir>    Directory for .img files (generate/extract output)
                           or sections to repack (repack input)
  -D  --default            Set directory and initrd from current boot mode:
                             live:      initrd = /live/boot-dev/antiX/initrd.gz
                                        dir    = ./initrd.gz.D
                             installed: initrd = /boot/initrd.img-<kver>
                                        dir    = ./initrd.img-<kver>.D
                           explicit -d or -i always overrides -D
      --amd-dir=<dir>      AMD firmware source  [default: /lib/firmware/amd-ucode]
      --intel-dir=<dir>    Intel firmware source [default: /lib/firmware/intel-ucode]
  -F  --firmware=<path>    Firmware base: directory (auto-sets amd-ucode/ and
                           intel-ucode/ sub-dirs) or squashfs image (auto-mounted)
  -i  --initrd=<file>      Update this initrd in-place:
                             strip old ucode CPIOs, prepend new ones,
                             refresh <initrd>.md5 if present,
                             run e4defrag if on ext4
  -k  --keep               Keep generated .img files when using a temp dir
                           (only meaningful when -i is given without -d)
  -S  --strip              Strip ucode CPIOs from -i <initrd> without adding new
                           ones; other preamble sections are kept intact
  -H  --has-ucode          Check if -i <initrd> contains ucode CPIOs;
                           exits 0=found, 1=none  (no writes)
  -x  --extract[=<mode>]   Extract initrd sections to -d <dir> (must be empty or new):
                             (bare)    ucode CPIOs only
                             =all     all sections as raw files
                             =unpack  all sections + unpack each into <name>.D/
  -l  --list[=<mode>]      List initrd sections (no files written):
                             (bare)    ucode CPIOs only -- vendor, size, files
                             =all     all sections -- name, size, compression
                             =unpack  all sections + list files inside each
      --repack=<dir>        Repack sections from <dir> back into -i <initrd>;
                             uses <name>.D/ if it exists, else the raw file
  -h  --help               Show this usage
  -n  --no-color           Suppress ANSI color codes in output
  -q  --quiet              Suppress all progress output; only fatal errors shown
  -s  --silent             Only show error messages
  -V  --verbose            Show commands as they run
  -v  --version            Show version and exit

Building the .deb

Requirements: devscripts, debhelper

sudo apt install devscripts debhelper

From the repository root:

cd deb-src
make

This copies the current uc-tool script into the source tree and runs debuild -uc -us to produce uc-tool_<version>_all.deb in deb-src/.

Or build manually:

cd deb-src/uc-tool-mx
cp ../../uc-tool .
debuild -uc -us

To bump the version before building:

1. Edit VERSION= near the top of uc-tool
2. Add a new entry to deb-src/uc-tool/debian/changelog:

   cd deb-src/uc-tool
   dch -v 1.1 "Your change summary"

3. Run make from deb-src/

License

GNU General Public License v3 — see debian/copyright or https://www.gnu.org/licenses/gpl-3.0.html.

Copyright © 2026 fehlix <fehlix@mxlinux.org>
Copyright © 2026 MX Linux Development Team <https://mxlinux.org\>