You installed Proxmox VE, got your first VM running, and now there's a little red badge or an email in your inbox telling you updates are available. Do you click it? Do you wait? What actually happens to your running VMs if you do?
This is one of those things nobody explains clearly when you're new to Proxmox. Updating a hypervisor isn't like updating your phone. There's a host operating system underneath every VM and container you're running, and if you botch the update, you don't just lose an app — you can lose access to everything sitting on that node. That sounds scary, but the actual process is pretty forgiving once you understand what's happening under the hood.
This guide walks through updating Proxmox VE 8.x the way Proxmox's own team recommends: which repository to use, which commands to run, when a reboot is actually required, and the mistakes that turn a five-minute update into a weekend project.
What You Will Learn
- The difference between the enterprise, no-subscription, and test repositories, and which one you should actually be using
- How to update Proxmox VE safely from both the command line and the web interface
- What
apt update,apt full-upgrade, andpveversionactually do - When a reboot is required and when it isn't
- The errors you're most likely to hit, and how to fix each one
- How updating a clustered node differs from updating a single standalone box
What Does "Updating Proxmox VE" Actually Mean?
Proxmox VE is built on Debian. Underneath the web interface, the cluster manager, and the virtualization stack, you're running a full Debian install — Debian 12 "Bookworm" for the current Proxmox VE 8.x series. When you update Proxmox, you're really running Debian's package manager, apt, against a set of repositories that mix regular Debian packages with Proxmox's own packages: the kernel, the web UI, qm and pct tooling, and everything else that makes Proxmox, well, Proxmox.
That matters because it means updating isn't some proprietary black-box process. It's the same apt update and apt full-upgrade you'd run on any Debian server, just pointed at repositories that also carry Proxmox-specific packages. Once you know that, the whole thing stops feeling mysterious.
There's a separate, bigger event called a major version upgrade — going from Proxmox VE 8 to Proxmox VE 9, for example — which involves changing the underlying Debian release entirely and needs its own careful process. This guide is about the routine stuff: the point releases and package updates that happen throughout the life of a single major version, roughly every few weeks.
Why Bother Updating Regularly?
Security patches are the obvious reason. Proxmox ships fixes for the kernel, QEMU, and the web stack on a rolling basis, and some of those fixes matter — a stale kernel is a real attack surface if your Proxmox host is reachable from anywhere semi-public.
But it's not just security. Bug fixes land in these updates too. If you've hit a weird glitch where a VM hangs on shutdown, or backups silently fail on a particular storage type, there's a decent chance someone already reported it and a later package already fixes it. Waiting six months between updates means you're carrying every bug from that whole window, not just the ones you've noticed.
There's also a practical argument for staying current: falling too far behind makes future upgrades harder. Jumping from a Proxmox VE install that's two years stale straight to the latest point release can trigger dependency conflicts that a steady drip of monthly updates would have avoided entirely. Small, frequent updates are boring. Boring is what you want from infrastructure.
Prerequisites
Before touching anything, make sure you have:
- Root or sudo access to your Proxmox VE host, either via SSH or the built-in web shell
- A Proxmox VE 8.x installation (the commands below apply to the 8.x series; if you're still on 7.x, update within 7.x first before considering a major upgrade)
- Recent backups of anything you can't afford to lose — not because updating is likely to destroy data, but because "likely" isn't "never"
- A maintenance window where a short reboot won't take down something someone else depends on
- If you're running a cluster, access to every node, since you'll be updating them one at a time, not all at once
You don't need a subscription to update Proxmox VE. Plenty of homelab and small business installs run entirely on the free no-subscription repository, which gets the same packages as the enterprise repository, just a little sooner and with less pre-release testing behind them.
Step-by-Step Tutorial
Step 1: Check Which Repository You're On
Fresh Proxmox VE installs default to the enterprise repository, which requires a paid subscription key to actually pull packages from. If you don't have one, apt update will throw authentication errors on that repository specifically — annoying, but harmless, and easy to fix.
Check what's configured:
cat /etc/apt/sources.list.d/pve-enterprise.list
cat /etc/apt/sources.list.d/pve-no-subscription.list 2>/dev/nullOn some newer installs these live as deb822-format .sources files instead of the older single-line format, so also check:
ls /etc/apt/sources.list.d/Step 2: Switch to the No-Subscription Repository (If Needed)
If you don't have a subscription, disable the enterprise repository and enable no-subscription instead. Easiest way is through the GUI: click your node in the left tree, open Repositories, select the pve-enterprise entry, and click Disable. Then click Add, choose No-Subscription, and confirm.
Doing it by hand is just as quick. Comment out the enterprise line and add the no-subscription one:
echo "deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription" > /etc/apt/sources.list.d/pve-no-subscription.listThen open /etc/apt/sources.list.d/pve-enterprise.list and either comment out the line with a # or delete the file outright.
Step 3: Refresh the Package Index
apt updateThis doesn't install anything yet — it just pulls the latest list of available package versions from each configured repository. If this step throws errors, fix those before going any further. Running an upgrade against a stale or broken package index is how you end up with half-installed packages.
Step 4: See What's Going to Change
apt list --upgradableSkim the list. Most of the time it's routine — a new kernel point release, some library bumps, maybe a newer pve-manager. Occasionally you'll spot something worth pausing on, like a new kernel major version or a Ceph package if you're running hyper-converged storage. If anything looks unusual, a quick search of the Proxmox forum for that package name and version usually turns up whether anyone else has hit trouble with it.
Step 5: Run the Upgrade
apt full-upgradeUse full-upgrade, not plain upgrade. Proxmox's own documentation recommends it specifically because Proxmox package updates occasionally need to remove an obsolete package to satisfy a new dependency, and plain apt upgrade refuses to do that — it'll just leave the conflicting package "held back" and silently skip the update instead of telling you clearly why.
Read the prompts. apt will sometimes ask whether to keep your locally modified config file or take the maintainer's version — for something like /etc/ssh/sshd_config, keep yours unless you know exactly what changed upstream.
Step 6: Reboot If a New Kernel Was Installed
Check whether the kernel you're running matches the kernel that's actually installed:
uname -r
pveversion -v | grep runningIf they don't match, a newer kernel got installed but isn't active yet — you're still running the old one in memory. Nothing breaks by leaving it that way for a while, but you won't get the benefit of whatever the new kernel fixed until you reboot. On a standalone box with no VMs currently doing anything critical, just reboot:
rebootOn a node with running VMs you care about, migrate them off first if you're in a cluster, or at least give people a heads-up if it's a shared box. A reboot takes maybe two to five minutes depending on your hardware and how much storage needs to re-mount, but every VM on that node goes down for that window unless you migrated it elsewhere first.
Step 7 (Clusters Only): Update One Node at a Time
If you're running a Proxmox VE cluster, resist the urge to SSH into all your nodes and run the update in parallel. Update one node fully — including the reboot — confirm it rejoins the cluster and shows healthy in pvecm status, and only then move to the next. This is doubly important if you're running Ceph, since Ceph tracks its own version compatibility between OSDs and monitors, and having every node drop out simultaneously is a good way to lose quorum at the worst possible moment.
Commands Explained
| Command | What It Does |
|---|---|
apt update | Refreshes the local list of available package versions from configured repositories. Installs nothing. |
apt list --upgradable | Shows every package with a newer version available, without changing anything. |
apt full-upgrade | Installs all available upgrades, removing conflicting packages if a dependency requires it. The recommended command for Proxmox VE. |
apt upgrade | Similar to full-upgrade but never removes packages — it holds back anything that would require a removal, which can silently skip Proxmox updates. |
pveversion -v | Prints the exact version of every Proxmox package installed, plus which kernel is currently running versus installed. |
pvecm status | Shows cluster membership and quorum state — run this after updating a clustered node to confirm it rejoined cleanly. |
apt autoremove | Removes packages that were installed as dependencies but are no longer needed by anything — commonly old kernel versions. |
dpkg --configure -a | Resumes a package installation that got interrupted partway through, finishing any half-configured packages. |
Common Errors
"401 Unauthorized" or "Your subscription level does not allow..." when running apt update. This means the enterprise repository is still enabled without a valid subscription key attached to it. Switch to the no-subscription repository as shown in Step 2, or purchase a subscription if this is a production box you want on the more heavily tested channel.
"The following packages have been kept back." You ran apt upgrade instead of apt full-upgrade. Some Proxmox package needed to remove another package to proceed, and plain upgrade won't do that automatically. Re-run with apt full-upgrade.
"E: dpkg was interrupted, you must manually run 'sudo dpkg --configure -a' to correct the problem." Usually caused by an SSH session dropping mid-upgrade, a power blip, or someone hitting Ctrl+C at the wrong moment. Run the suggested command, let it finish, then re-run apt update && apt full-upgrade to pick up where things left off.
"You don't have enough free space in /boot." This one catches people who never reboot. Old kernel versions pile up in /boot over successive updates, and eventually there's no room for a new one. Run apt autoremove to clear out kernels that are no longer in use, then retry the upgrade.
"E: Repository ... does not have a Release file." Something in your sources list points at a URL or suite name that doesn't exist — a typo from manual editing, most commonly. Double-check the exact repository line against the official Proxmox documentation for your version and fix the typo.
Troubleshooting
If the web interface won't load after an update but the host still responds to ping and SSH, the pveproxy service is the usual suspect. Restart it and check its status:
systemctl restart pveproxy
systemctl status pveproxyIf that comes back clean but the UI is still blank or throwing a 596 error, restart pvedaemon and pvestatd as well — occasionally one of the three gets stuck mid-restart during a package upgrade and needs a manual nudge.
If a node won't boot at all after a kernel update, don't panic and don't reinstall. At the GRUB menu (or the systemd-boot menu if you're on ZFS root), you can usually select the previous kernel version and boot into that instead, giving you a working system to investigate from. From there, check journalctl -b -1 -p err to see what the failed boot logged before it died, and search that specific error against the Proxmox forum — kernel regressions do happen occasionally and they're almost always already reported with a workaround by the time you hit them.
If a cluster node comes back up but pvecm status shows it as not part of the quorum, check that its clock hasn't drifted and that the corosync service actually started:
systemctl status corosync
dateA few seconds of clock drift is fine, but minutes of drift will cause cluster communication problems.
Best Practices
Read the changelog before you upgrade, not after something breaks. The Proxmox forum has an announcement thread for every point release, and skimming it takes two minutes.
Stagger cluster updates across separate days if you're risk-averse, or at least separate maintenance windows. There's no rule against updating all nodes in one sitting once you're comfortable with the process, but going one at a time the first few times builds the muscle memory for spotting when something's actually wrong versus just taking a while.
Keep a recent backup of anything important before a major point release, even though routine updates rarely cause data loss. It's cheap insurance against the rare case, and honestly, you should have current backups regardless of whether you're about to update anything.
Don't update right before you're about to be unreachable for a week. If something does go sideways — a driver regression, a networking hiccup after a reboot — you want to be around to fix it, not find out from an angry text three days later.
Avoid running apt upgrade or full-upgrade unattended via a cron job on Proxmox hosts. It's tempting to automate, and plenty of people do it on plain servers, but a kernel update that needs a reboot and a hypervisor full of other people's VMs is not somewhere you want surprises.
If you're on the no-subscription repository for a production system, that's a legitimate choice plenty of shops make — just understand you're trading a bit of pre-release testing for cost savings, and budget slightly more caution around update day as a result.
Frequently Asked Questions
Do I need a subscription to update Proxmox VE?
No. The no-subscription repository is free and gets the same packages, just without the extra testing pass the enterprise repository goes through first.
Will updating Proxmox VE update my VMs and containers too?
No. Updating the host only touches the Proxmox VE host system itself. Each VM or LXC container runs its own operating system and needs its own updates run separately, inside the guest.
How often should I update?
Every few weeks is reasonable for most homelab and small business setups. There's no fixed schedule Proxmox enforces — it's really about how much risk tolerance you have versus how current you want to stay on security fixes.
Do I always need to reboot after updating?
Only if a new kernel was installed, or occasionally after certain low-level package updates. Compare uname -r against the running kernel line in pveversion -v to check.
What's the actual difference between apt upgrade and apt full-upgrade?
full-upgrade will remove a package if that's required to install a newer version of something else. Plain upgrade refuses to remove anything, so it just skips those updates instead — which on Proxmox often means it skips exactly the update you needed.
Can I downgrade a package if an update breaks something?
Technically yes with apt install packagename=version, but it's not officially supported and can leave your system in an inconsistent state. Booting the previous kernel from the boot menu is a much safer way to work around a bad kernel update specifically.
Is it safe to update through the web GUI instead of SSH?
Yes. The Updates tab on your node runs the exact same apt update and apt full-upgrade commands under the hood, just through a browser-based console window instead of a terminal session.
Final Thoughts
Updating Proxmox VE really is just Debian package management with a couple of Proxmox-specific habits layered on top: know which repository you're using, run full-upgrade instead of plain upgrade, and reboot when the kernel actually changed. None of that is complicated once you've done it a handful of times.
The nodes that get into trouble are almost always the ones that went eighteen months without a single update, then tried to catch up all at once under pressure. Do it in small, boring increments instead, and updating a Proxmox host stops being an event you dread and turns into something you barely think about — which is exactly how infrastructure maintenance should feel.