Snapdragon firmware extraction on Omarchy

qcom-firmware-extract on Omarchy

qcom-firmware-extract is a small GPL-licensed script (12 KB) that copies the vendor-signed Qualcomm firmware your Snapdragon laptop needs — GPU zap shader, audio/compute DSP images — out of your own Windows installation and into Linux’s firmware directory. It’s for Snapdragon X (Elite/Plus) laptops running Omarchy; everyone else can ignore it.

TL;DR

omarchy pkg add qcom-firmware-extract

On a running system, use it with sudo qcom-firmware-extract — it scans your internal disks for a Windows partition, copies only the firmware files your device tree says the kernel will ask for and that aren’t already in /usr/lib/firmware, installs them under /usr/lib/firmware/updates/, rebuilds the boot image, and tells you to reboot. Two hard requirements, straight from the package docs: your machine must have a Qualcomm device tree (a non-Snapdragon machine makes the tool exit immediately), and the Windows partition must not be BitLocker-encrypted — turn BitLocker off in Windows first, because the tool can only mount the NTFS partition read-only when it isn’t encrypted.

Getting started (5 minutes)

1. Know whether you need it.

Run sudo qcom-firmware-extract --list-missing — it lists the firmware names your device tree wants that are missing under /usr/lib/firmware. Nothing missing (for example, because linux-firmware now ships your machine’s vendor directory — true for some ThinkPads) means the tool copies nothing and you’re done. No device tree at all means it exits at once. Most Omarchy users on Intel/AMD/Apple hardware will never need this package.

2. Prepare the source.

If you’re dual-booting: boot Windows once, turn off BitLocker (Settings → Privacy & security → Device encryption), and shut down fully — no hibernation, no Fast Startup holding the NTFS partition dirty. If you already wiped Windows: get the FileRepository driver store from a Windows install of the same model (a friend’s identical laptop, a recovery image, a USB copy).

3. Run it.

sudo qcom-firmware-extract              # scan internal disks, install what's missing, rebuild boot image
sudo qcom-firmware-extract -d /mnt/usb/FileRepository   # use an external driver store instead

Reboot afterwards. The GPU zap shader is added to the initramfs via /etc/mkinitcpio.conf.d/qcom-firmware.conf (the limine-mkinitcpio-hook optdepends handles rebuilding the boot image); the DSP images load from the root filesystem at boot.

4. The three things everyone needs to know:

• The package contains no firmware. It’s a copier, not a distributor — the files it copies never leave your machine and are never downloaded. That’s deliberate: these are vendor-signed blobs Qualcomm and the laptop vendors haven’t contributed to linux-firmware, and the tool is explicitly “a temporary measure until laptop vendors contribute complete firmware sets to linux-firmware.” When linux-firmware ships your machine’s vendor directory, the tool copies nothing — and when every supported machine is covered, the package gets dropped entirely.
• The device tree is the source of truth. The tool doesn’t guess: it reads the firmware-name properties from your running device tree, keeps the names that are missing, and finds each one by filename in Windows/System32/DriverStore/FileRepository. A DSP image the device tree calls *_dtb.mbn is also found under its Windows name *_dtbs.elf. When Windows carries several variants and linux-firmware has a companion image from the same device-tree node, the sibling image’s hash picks the compatible variant; ambiguous variants with no unique match are skipped, not guessed.
• Everything is recorded. What was installed, where it came from, and its checksum goes into /var/lib/omarchy/qcom-firmware/manifest. If you ever need to audit, roll back, or hand the machine to someone, that manifest is the paper trail. (Board packages can also exclude names that must not come from Windows via /usr/share/qcom-firmware-extract/provided.d/<compatible>.list — listed names are never searched, installed, or reported missing.)

Common issues & fixes

All sourced from the package’s bundled README.package.md and the Ubuntu Concept Snapdragon discourse the tool derives from.

The tool can’t read the Windows partition / finds nothing

Fix: The documented cause is BitLocker: “BitLocker volumes cannot be read; turn BitLocker off in Windows first.” Boot Windows, disable device encryption, and fully shut down (Fast Startup / hibernation also leaves the NTFS volume in a state Linux won’t mount cleanly). Then re-run.

You already wiped Windows with a full-disk install and now firmware is missing

Fix: The installer only gets one chance — it runs qcom-firmware-extract --stage DIR “right after the disk is chosen, before anything is written” precisely because “a full-disk install destroys the Windows partition the files come from.” If you missed that window, the escape hatch is sudo qcom-firmware-extract -d /path/to/FileRepository pointed at a driver store from a Windows install of the same model (USB disk is fine). Same model matters: “the files are tied to the vendor’s signing keys.”

Some firmware is still missing after a run, or a variant was “skipped”

Fix: Per the README, when Windows carries several variants of a file and there’s no companion image in linux-firmware to disambiguate by hash, the tool skips rather than installs the wrong signed blob. Check --list-missing to see what’s still absent, and check whether your board’s package handles that name itself (provided.d/<compatible>.list) — some boards process a vendor driver file or deliberately hold back an untested image. When in doubt, ask in the Snapdragon-on-Linux community with your exact model and the missing filename.

On some machines (e.g., ThinkPad T14s) the tool copies nothing at all

Fix: That’s the retirement path working: “When linux-firmware ships a machine’s vendor directory, the tool copies nothing.” Per the Ubuntu Concept discourse, the T14s’s signed firmware landed in linux-firmware, so extraction became unnecessary there — but “the devices use signed blobs with keys that differ for each hardware,” so each model needs adding individually and “realistically not all laptops will ever be supported.” If --list-missing is empty, you don’t have a problem; you have a supported machine.

After installing firmware, early boot display still misbehaves

Fix: The GPU zap shader must be in the initramfs, not just on the root filesystem — that’s what /etc/mkinitcpio.conf.d/qcom-firmware.conf is for, and the tool rebuilds the boot image itself. If you ran with --no-rebuild (as the installer does, building once afterwards) or interrupted it, make sure the limine-mkinitcpio-hook optdepends is installed and the boot image was actually rebuilt, then reboot. The DSP images, by contrast, load from the root filesystem and don’t need the initramfs.

Pairs well with / If you hate this, try

Pairs well with

• linux-firmware-qcom (Arch’s packaged Qualcomm firmware — the tool complements it, and a machine it fully covers needs no extraction). The limine-mkinitcpio-hook optdepends (rebuilds the boot image after firmware lands). The manifest at /var/lib/omarchy/qcom-firmware/manifest — your audit trail.

If you hate this, try

• Doing it by hand — the manifest and the README tell you exactly which filenames go to /usr/lib/firmware/updates/ and which config the initramfs needs. But there’s no real alternative tool; the “alternative” is waiting for your vendor to upstream firmware to linux-firmware, at which point this package retires itself.

Comparison: getting Qualcomm firmware onto Linux

Verdict: Use qcom-firmware-extract if you’re on a Snapdragon X laptop and --list-missing shows gaps; use nothing at all if linux-firmware already covers your machine; go manual only when you’re debugging one specific file.