You ran apt full-upgrade on a Friday afternoon, rebooted like always, and now your GPU passthrough VM won't start. Or your 10GbE NIC dropped off the network. Or a Ceph OSD refuses to come back up. The update itself looked clean — no errors, no held-back packages — but the new kernel that came with it broke something the old one didn't.
This happens more often than Proxmox's release notes let on. Kernel updates touch drivers, IOMMU behavior, and low-level storage code, and every so often a regression slips through that only shows up on specific hardware. The good news is you're not stuck. Proxmox VE keeps your previous kernels installed after an update, and it ships a tool specifically for booting back into one of them — and keeping it there until you're ready to move on.
This is a deeper, more specific companion to a general Proxmox update guide. It doesn't cover how to run apt full-upgrade safely — it covers what to do once a kernel from that upgrade has already caused you trouble, and how to stop it from happening again on the next update.
What You Will Learn
- What kernel pinning actually does in Proxmox VE, and why it's different from just not updating
- How to see which kernels are installed on your host right now
- How to boot a previous kernel from the GRUB or systemd-boot menu at startup
- How to pin a kernel with
proxmox-boot-toolso it keeps loading after future updates - How to tell whether your host uses GRUB or systemd-boot, since the commands differ slightly
- The errors you're most likely to run into, and how to fix each one
What Is Kernel Pinning in Proxmox VE?
Proxmox VE is built on Debian, and the kernel is one of the packages that gets updated along with everything else when you run apt full-upgrade. Unlike a lot of Debian packages, though, Proxmox doesn't remove your old kernel the moment a new one lands. Both versions sit on disk side by side for a while — the previous one stays available specifically so you have somewhere to fall back to.
Kernel pinning is how you tell Proxmox which of those installed kernels should actually load when the machine boots. Left alone, Proxmox VE boots the newest kernel it has by default, every time. Pinning overrides that: it locks the boot process to a specific version you choose, and it keeps choosing that version even after the next update installs something newer.
The tool that does this is called proxmox-boot-tool. It's already installed on every current Proxmox VE 9.x host — you don't need to add anything. What it actually manages depends on how your system boots. On a UEFI install with a ZFS root filesystem, Proxmox uses systemd-boot and stores kernel entries on small FAT-formatted partitions called ESPs (EFI System Partitions), usually one on each disk in your root pool for redundancy. On most non-ZFS installs, Proxmox uses classic GRUB instead, and proxmox-boot-tool mostly just triggers update-grub behind the scenes rather than managing ESPs directly.
You don't need to know which one you have before starting — there's a command in the tutorial below that tells you.
Why Would You Want to Pin a Kernel?
The most common reason is a driver regression. Realtek and some Intel NICs have a history of losing features or dropping links entirely on specific kernel point releases. GPU passthrough setups are even more sensitive — a kernel bump can change how VFIO binds to a device, and a passthrough VM that worked perfectly on 6.14 might refuse to start on 6.17 until a fix lands.
ZFS is another one. The OpenZFS module has to be rebuilt against whatever kernel you're running, and occasionally a brand-new kernel ships slightly ahead of ZFS's own compatibility updates. On a ZFS-root box, that's not a cosmetic problem — it's the difference between booting and not booting.
There's also a simpler reason that has nothing to do with bugs: you're running a cluster, and you want every node on the exact same kernel version before you touch the next one. Pinning gives you that control explicitly instead of hoping every node happened to update at the same moment.
None of this means you should pin a kernel and forget about it. Pinning is a deliberate, temporary override — a way to buy yourself time until the thing that broke gets fixed upstream, not a permanent policy for how you run your host.
Prerequisites
Before you start, you'll want:
- Root or sudo access to the Proxmox VE host, either via SSH or the web-based shell
- At least two kernel versions currently installed — if you've only ever run one kernel, there's nothing to fall back to yet
- Physical or remote console access (IPMI, iDRAC, iLO, or a monitor and keyboard) if the host currently fails to boot, since you'll need to reach the boot menu directly rather than SSH in
- A few minutes of downtime for any VMs on the node, since selecting a different kernel requires a reboot
This guide assumes Proxmox VE 9.x, currently on the 9.2 release built on Debian 13 "Trixie." The commands are the same on Proxmox VE 8.x, though the default kernel version numbers will obviously differ.
Step-by-Step Tutorial
Step 1: Check Which Bootloader You're Using
The commands you'll run later depend slightly on whether your host uses GRUB or systemd-boot. Check with:
proxmox-boot-tool statusIf the output lists ESP entries with UUIDs, you're on systemd-boot — typically the case on ZFS-root or UEFI installs Proxmox set up itself during installation. If instead you see a message that this system isn't managed by proxmox-boot-tool ESPs, you're on plain GRUB, most common on ext4 or LVM installs, or on older BIOS-boot systems.
Step 2: List the Kernels You Have Installed
See every kernel package currently on disk:
dpkg -l | grep pve-kernelYou'll get a list like pve-kernel-6.14.11-4-pve and pve-kernel-6.17.2-1-pve, each tagged ii for installed. Compare that against what's actually running right now:
uname -rIf uname -r shows an older version than the newest one in your dpkg list, you're already running a fallback kernel — maybe from a previous reboot into the boot menu, or because the newest one failed to boot and the system defaulted back.
Step 3: Boot the Older Kernel Once, to Confirm It's the Fix
Before pinning anything permanently, reboot and manually select the older kernel from the boot menu, to confirm it actually resolves your problem rather than assuming it will.
| Bootloader | How to reach the menu | What you'll see |
|---|---|---|
| GRUB | Watch the console during POST; GRUB's menu appears as a blue-and-white text screen. If it flashes by too fast, hold Shift (BIOS) or tap Esc repeatedly (UEFI) right after power-on. | A list titled "Advanced options for Proxmox VE GNU/Linux" containing an entry per installed kernel |
| systemd-boot | Tap the spacebar during the firmware's boot device selection, before Proxmox starts loading | A simpler black-and-white menu listing each pinned/available kernel version directly |
Select the older kernel, let it boot, and go test whatever was broken — start the passthrough VM, check the NIC link, whatever it was. If it works, move to Step 4. If it doesn't, the kernel probably wasn't your problem, and pinning it won't fix anything.
Step 4: Pin the Kernel That Works
Once you've confirmed which version behaves correctly, pin it so it survives future updates. Use the exact version string from dpkg -l | grep pve-kernel, without the pve-kernel- prefix:
proxmox-boot-tool kernel pin 6.14.11-4-pveThis sets that version as the one Proxmox boots by default going forward, even after a newer kernel gets installed later. If you only want it for the very next boot — say, you're testing something and plan to switch back — add --next-boot instead:
proxmox-boot-tool kernel pin 6.14.11-4-pve --next-bootStep 5: Sync the Change to Your Boot Partitions
Pinning updates Proxmox's own configuration, but on systemd-boot systems you still need to push that change out to each ESP:
proxmox-boot-tool refreshSkip this step and the pin quietly does nothing — the system keeps booting whatever it was booting before, and you'll assume the pin failed when really it just never got synced. On GRUB systems this step is less critical since proxmox-boot-tool typically calls update-grub automatically, but running it again costs nothing and rules out doubt.
Step 6: Reboot and Verify
rebootOnce it's back up, confirm the pin actually took:
uname -rIt should match the version you pinned. From here you can keep updating Proxmox normally — apt full-upgrade will still install newer kernel packages when they're available, it just won't switch your active boot target away from the pinned one until you say so.
Step 7: Remove the Pin Once It's No Longer Needed
Don't leave a pin in place forever. Once the regression that caused you trouble gets fixed in a later kernel — check the Proxmox forum's kernel release threads periodically — remove the pin and go back to normal:
proxmox-boot-tool kernel unpin
proxmox-boot-tool refresh
rebootThis is easy to forget, and a forgotten pin from eight months ago is exactly the kind of thing that costs you an afternoon of confused troubleshooting when you can't figure out why a "fixed" driver bug is still happening on your box.
Commands Explained
| Command | What It Does |
|---|---|
proxmox-boot-tool status | Reports whether the host is managed via systemd-boot ESPs or plain GRUB, and lists the ESP partitions if applicable. |
dpkg -l | grep pve-kernel | Lists every kernel package currently installed, whether or not it's the one currently running. |
uname -r | Shows the exact kernel version the system is running right now, in memory. |
proxmox-boot-tool kernel pin <version> | Locks future boots to the specified kernel version until it's explicitly unpinned. |
proxmox-boot-tool kernel pin <version> --next-boot | Boots the specified version exactly once; the system reverts to normal selection after that boot. |
proxmox-boot-tool kernel unpin | Removes any active pin and returns to Proxmox's default behavior of booting the newest installed kernel. |
proxmox-boot-tool refresh | Pushes the current kernel/pin configuration out to every ESP, required after any pin or unpin on systemd-boot systems. |
proxmox-boot-tool kernel list | Shows which kernel versions are currently selected for booting and which one, if any, is pinned. |
apt-mark hold pve-kernel-<version> | Prevents that specific kernel package from being removed or upgraded by apt, useful alongside pinning if you want to guarantee the package itself stays on disk. |
Common Errors
"E: /etc/kernel/proxmox-boot-uuids does not exist." You're running plain GRUB, not systemd-boot ESPs, so proxmox-boot-tool has nothing to manage there. Pinning still works through the same commands, but skip worrying about ESPs — GRUB reads its config from /boot/grub instead, and update-grub handles the rest.
The GRUB menu never appears — the system boots straight into Proxmox. A short or zero GRUB_TIMEOUT in /etc/default/grub is the usual cause. Set GRUB_TIMEOUT=5, run update-grub, and try again. Tapping Esc or Shift right at power-on, before the Proxmox splash appears, also works even with a short timeout on most hardware.
The pin doesn't seem to do anything after a reboot. Almost always means proxmox-boot-tool refresh was skipped after pinning. Run it again, then reboot.
"kernel pin: Version ... not found among the installed kernels." You typed the version string slightly wrong. Copy it directly out of dpkg -l | grep pve-kernel rather than retyping it from memory — a missing digit in the build number is the most common cause.
The pinned kernel disappeared after a later update. Pinning protects a kernel from the automatic cleanup that runs during package updates, but it doesn't protect it from an explicit removal command. If you or a script ran apt autoremove and answered yes to removing old kernels, apt will happily remove even a pinned one — apt doesn't know pinning is a thing, only proxmox-boot-tool does. Reinstall the specific package with apt install pve-kernel-6.14.11-4-pve if it's still available in your repository, and consider apt-mark hold on top of the pin next time.
Troubleshooting
If the host is already stuck — it won't boot into the newest kernel at all, maybe it hangs, panics, or drops to an emergency shell — don't reinstall Proxmox. Reboot, catch the boot menu using the timing in Step 3 above, and manually select the previous kernel entry for that one boot. That gets you back to a working system where you can pin the older version properly and investigate at your own pace, instead of under pressure with a dead host.
If neither GRUB nor systemd-boot shows a menu at all, even with correct timing, check what firmware mode the machine actually booted in:
efibootmgr -vA missing or empty EFI boot entry for Proxmox usually points to a firmware setting issue — Secure Boot enabled without the right shim, or the boot order pointing at the wrong disk — rather than anything wrong with the kernel selection itself. That's a separate problem from what this guide covers, and worth fixing before you spend more time on kernel pinning.
If you're on a cluster and pinned different kernel versions on different nodes without meaning to, check each node individually with uname -r over SSH rather than assuming they matched just because you ran the same update command everywhere. Mixed kernel versions across a cluster aren't necessarily broken, but they're worth knowing about, especially if you're running Ceph, where the underlying kernel can affect RBD client behavior.
Best Practices
Treat a pin as a sticky note, not a config file you forget about. Write down somewhere — a note, a ticket, whatever you actually check — which kernel you pinned, why, and what upstream fix you're waiting on.
Keep at least two kernels installed at all times, ideally three. Proxmox's own cleanup process already tends to do this, but don't manually prune down to a single kernel just to save a few hundred megabytes of boot partition space. That single kernel is your only fallback if the next update goes badly.
Test new kernels on a non-critical node first if you're running a cluster. Pin the rest of the cluster to the known-good version, update one expendable node to the newest kernel, and watch it for a day or two before rolling the update out everywhere else.
Before a major version upgrade — Proxmox VE 8 to 9, for instance — remove any active pins first. A pin from the old major version can interfere with the new bootloader configuration the upgrade process sets up, and it's one less variable to debug if the upgrade itself hits a snag.
Check the Proxmox forum's kernel announcement threads before jumping onto a brand-new kernel on a production box, especially right after it first appears in the no-subscription repository. Homelab hardware quirks and driver regressions usually surface there within days.
Frequently Asked Questions
Does pinning a kernel stop security updates?
No. Package updates keep installing normally, including newer kernel packages. Pinning only controls which kernel actually boots — it doesn't pause apt full-upgrade or hold back anything else on the system.
Do I need proxmox-boot-tool if I'm not using ZFS?
You still have it installed and can still use it, but on a non-ZFS, non-UEFI-ESP install it mostly acts as a wrapper around GRUB rather than managing ESP partitions directly. The pin and unpin commands work the same either way.
How many kernels does Proxmox keep around by default?
It varies by release and isn't a fixed number you should rely on. Check for yourself with dpkg -l | grep pve-kernel rather than assuming — if you only see one or two, be extra cautious before your next update.
Can I pin a kernel that isn't currently installed?
No. You can only pin a version that's already sitting on disk. If the kernel you want was already removed by cleanup, reinstall it with apt install pve-kernel-<version> first, assuming it's still available in the repository you're using.
Will pinning break a future major version upgrade, like PVE 9 to PVE 10?
It can complicate one. Unpin before starting any major version upgrade, let the upgrade process manage the bootloader and kernel selection itself, then re-pin afterward only if you're still hitting the original problem on the new major version.
Is this the same as apt-mark hold?
Related, but not identical. proxmox-boot-tool kernel pin controls what boots. apt-mark hold controls whether apt is allowed to remove or upgrade a specific package. Using both together is the most reliable way to guarantee a specific kernel stays both installed and booted.
Final Thoughts
A kernel regression is one of the more unsettling things that can happen on a Proxmox host, mostly because it feels like it came out of nowhere — you didn't change anything, the update looked fine, and suddenly a VM or a NIC just stops working. Once you know Proxmox keeps your old kernels around and gives you a direct way to boot and pin them, that panic mostly goes away.
The commands themselves are small: check what's installed, boot the one that works, pin it, refresh, done. The habit that matters more than the commands is the follow-through — actually going back and unpinning once the fix lands upstream, instead of running the same "known good" kernel for the next two years out of inertia.