GPU Unlock Troubleshooting

Identify the failing stage

Begin with the first stage that failed, not the performance number you hoped to see. Package installation, early module loading, a per-card unlock, driver initialization and workload speed are separate outcomes. A change at one stage does not prove that every later stage succeeded.

This page covers the main Linux module. It does not prescribe UEFI changes for Windows experiments. For those, read the Windows recovery overview and the exact machine guide. If the system cannot boot normally, prioritize a recovery entry before collecting additional measurements. Keep your backups and original configuration available throughout diagnosis.

The package did not install

Symptom: the installer exits with a build, dependency or package-manager error. Possible conditions: automatic family detection did not fit the system, the matching kernel headers are missing, or the build environment cannot complete the selected package target.

Local check: preserve the original terminal error and identify the kernel you are running:

uname -r

Compare that version with the headers and package output for the kernel you intend to boot. The RPM installer requires DNF. A custom distribution is not made compatible by copying another distribution’s package command.

Next step: return to the automatic installation step and review the first error. Explicit installer targets are alternatives for compatible systems, not a sequence of fixes to run one after another.

Recovery: keep the opt-in parameter absent until installation and image generation complete. Do not change firmware or replace the NVIDIA driver simply because a package build failed.

There is no unlock result in the log

Symptom: packages appear installed, but no relevant current-boot result appears. Possible conditions: the intended kernel or entry was not booted, the opt-in is absent, the module was not included early enough, or module loading was rejected.

Local checks: inspect the current boot’s messages and its actual kernel command line:

journalctl -k -b | grep gpu_unlock
cat /proc/cmdline

Next step: compare the command line with the boot configuration you edited. Inspect installation output for an image rebuild or module-signing error. A configured file is not proof that the running entry consumed it. With a custom mkinitcpio config, verify the relevant MODULES order rather than assuming a drop-in was read.

Recovery: return to the known-good entry if the modified entry is unclear. The boot configuration guide separates GRUB, grubby, systemd-boot and generated UKIs so you can correct the source actually used by your system.

GPU already bound or powered off

Symptom: the module reports that a card was skipped because it is already bound or unavailable. Possible condition: NVIDIA or another driver initialized the device before the transaction, or power management turned the device off.

Local check: identify the actual full PCI address:

lspci -D

Then use lspci -nnk -s with that address to inspect binding. The README’s 0000:[ID]:00.0 is a placeholder, not your hardware identity. Read the corresponding per-card kernel messages alongside that binding information.

Next step: check that the package’s early initramfs path runs before NVIDIA. Loading the module manually after NVIDIA has bound the card does not unlock that card. Do not force a driver detachment as a generic workaround; display ownership and the firmware transaction have conditions that a model lookup cannot establish.

Recovery: disable the boot opt-in if early loading is not understood. For a powered-down laptop GPU, review the power-state section before changing settings.

The target parameter is wrong

Symptom: the intended card is not selected, an entry is ignored, or the observed boot command line differs from the saved setting. Possible conditions: a partial PCI address was used, an unsupported card was named, or all was mixed with explicit addresses.

Local check: compare the active parameter with your device locations:

cat /proc/cmdline
lspci -D

Next step: use the full BDF for a particular card or gpu_unlock.targets=all for the supported unbound cards, without combining the two forms. Check the device ID separately in the PCI ID snapshot. A PCI location and a device type are different identifiers.

After correcting the parameter, update the same boot configuration or generated image used originally. Preserve unrelated kernel options. If systemd-boot is your configured loader, bootctl status can help locate an entry; it is not a replacement for GRUB regeneration.

Recovery: remove the opt-in for one boot if selection is uncertain, then make the saved configuration consistent before another attempt.

Lost effect after idle or resume

Symptom: a result changes after idle, suspend or another power transition. Possible condition: powering the dedicated GPU down resets the selectors. A desktop cold-boot report does not establish a laptop’s behavior.

Local check: review the same boot’s log after the transition:

journalctl -k -b | grep gpu_unlock

Next step: identify which power transition occurred. The main project describes suspend-to-RAM handling with NVIDIA kernel notifier requirements. A suspend-to-idle card that retained power is a different case. Hibernation is not covered. The module may also refuse a card another driver already resumed.

The upstream laptop note discusses disabling NVIDIA runtime power management as a measure that helps some models, while explicitly expecting mixed results. It is not a universal fix and can affect power use. Review the exact environment before changing it.

Recovery: the advanced gpu_unlock.resume=0 parameter disables the module’s resume handling. Keep the original boot configuration so an experiment with resume policy is reversible.

No application speedup

Symptom: the per-card transaction appears successful but a game, quantized model or token-generation test shows little change. Possible condition: the application spends little time in the affected tensor path, or a power, memory or kernel-selection limit dominates.

Local check: preserve the current-boot result using the journal command above and record the exact workload and precision. Compare matched runs under the same power policy. A benchmark from another computer is not a locked baseline for yours.

Next step: use Benchmarks to separate issue rate, cuBLAS GEMM and application latency. Even a detailed RTX 4090 matched run had a BF16 matrix shape that did not improve. Unchanged decode or gaming performance is not, by itself, evidence of a failed transaction.

Recovery: if the benefit is not useful for your workload, remove the opt-in rather than escalating to unrelated overclocking, driver patches or firmware changes.

Boot or firmware failure

Symptom: the modified entry fails to start, the display does not recover, or the log reports firmware still running with DMA buffers retained. These cases need recovery, not another performance test.

Next step: for a boot problem, select the preserved unmodified entry or remove gpu_unlock.targets=… in the bootloader editor for that one boot. Once normal startup is restored, remove the saved opt-in and regenerate the matching configuration or images as described in Disable / roll back.

If firmware did not stop, upstream says to power off before trying again. The retained buffers may still be in use by firmware. Repeated module loading or forced unloading is not an appropriate substitute for the documented power-off recovery.

Package removal and boot-option removal are separate actions. Use the packages actually installed by your distribution; this guide does not invent a universal uninstall command. If you cannot identify the boot path or safely recover, stop and seek help for that specific system.

Sources & verification

Checks and recovery principles follow the main README, reviewed October 29, 2026. The additional uname -r and cat /proc/cmdline commands only inspect the running Linux environment; they do not alter the GPU. No local command is executed by this website. Original Linux instructions and limitations on GitHub.

Before sharing a report, remove private paths, identifiers and unrelated personal data from logs. Include the failing stage, relevant kernel messages, actual software versions and what recovery succeeded. A clear failure report is more useful than a screenshot claiming that the package installed.