The three repos, and which one you’re actually on

Proxmox ships three possible repository channels, and conflating them is where most of the confusion starts:

• Enterprise repo - the default pve-enterprise channel, gated behind a paid subscription key. This is the most conservative, slowest-moving channel, intended for production clusters that want updates vetted longest before they land.
• No-subscription repo - pve-no-subscription, free, no key required. This is what almost every homelab runs on. It gets the same packages as enterprise, just sooner, with less soak time behind it. Not “untested,” just newer.
• Test repo - pvetest, the bleeding edge, used by Proxmox’s own team and people chasing a specific not-yet-released fix. Don’t run this on anything you depend on.

A fresh install defaults to the enterprise repo with no valid subscription attached, which means apt update fails outright until you fix the repo configuration. Check /etc/apt/sources.list.d/pve-enterprise.list (or pve-enterprise.sources on newer installs using the deb822 format) and comment it out or remove it, then add the no-subscription line in its place, typically in /etc/apt/sources.list or a new file under /etc/apt/sources.list.d/. The exact line depends on your Debian base release codename, so pull it from Proxmox’s own wiki for whatever version you’re on rather than copying an old one forward. The subscription nag popup on login is cosmetic, tied to the missing key, not the repo channel, and some people hand-edit the UI’s JavaScript to suppress it. That edit gets silently reverted by the next package update that touches that file, so treat it as a nuisance to ignore rather than something worth fighting.

Pinning: when you need to hold one package back

Most of the time, letting apt dist-upgrade pull the newest available package is exactly what you want. The exception is a known regression, a kernel version with a driver bug that breaks GPU passthrough on your specific card, or a package you’ve deliberately tested against and don’t want moving until you’ve had a chance to validate the next one. Apt’s pinning mechanism handles this without you having to remember to skip a package by hand every time you update.

A pin lives in /etc/apt/preferences.d/ as a small file:

Package: pve-kernel-*
Pin: version 6.8.*
Pin-Priority: 1001

A priority above 1000 forces apt to install that version even if it counts as a downgrade from what’s currently installed, which matters if you’re pinning after a bad kernel already landed. A priority in the 500-999 range just means “prefer this if available, don’t force it.” Pinning the kernel metapackage is the most common homelab use case, since kernel regressions are the ones most likely to show up as a dead passthrough device or a flaky NIC after a routine update. Remove the pin file once the next kernel release actually fixes the regression, otherwise you end up stuck on an old kernel indefinitely while telling yourself you’ll get to it later.

Routine point-release updates

For the common case, staying current within a major version, the process is uneventful: apt update, then apt dist-upgrade (not plain apt upgrade, Proxmox’s own packages sometimes need to add or remove dependencies that upgrade won’t touch), review what’s queued to change before confirming, then reboot if a new kernel landed. Check pveversion after rebooting to confirm you’re actually running the kernel you think you are, since GRUB defaults can occasionally boot an older entry if something about the bootloader config is off. Do this regularly rather than letting point releases stack up for months, since the gap between your version and the current major release is exactly what makes the eventual major jump riskier.

Before attempting a major version jump

A major version upgrade (crossing a full number, not a point release) changes the underlying Debian base, the kernel line, and sometimes storage or clustering internals, not just Proxmox’s own packages. Treat it as a project, not a routine update, and do the following first, every time:

1. Back up everything that matters. A full PBS backup (or vzdump if you’re not running PBS) of every VM and container, plus a copy of /etc/pve itself, which holds your cluster config, storage definitions, and firewall rules. If the upgrade goes sideways, you want the ability to rebuild from scratch, not just roll a snapshot back.
2. Get fully current on your existing major version first. Don’t jump from three point-releases behind straight into the next major version. Run the routine update process above until pveversion shows you’re on the latest release of your current major line.
3. Run Proxmox’s own upgrade-readiness checker. Proxmox ships a dedicated script for each major transition (the naming pattern has been pveX to Y historically, check the current wiki page for the exact command for whatever jump you’re making). It checks things a careless apt dist-upgrade won’t catch: deprecated config syntax, storage types no longer supported, cluster nodes not yet ready, ZFS pool features that need upgrading separately. Read every warning it prints and resolve it before touching the sources list. A clean pass from this script is the actual green light, not just “the current version works fine today.”
4. If you’re running a cluster, upgrade one node at a time. Never run dist-upgrade across every node simultaneously. Pick one, upgrade it fully, confirm it rejoins the cluster and quorum is intact, then move to the next. Running two major versions side by side briefly during the rollout is expected and supported for exactly this reason; running them side by side for weeks because you lost momentum partway through is not a state to leave a cluster in.
5. If you’re running Ceph, its upgrade is a separate, ordered process from the host OS upgrade. Ceph has its own version compatibility rules and its own upgrade sequence (mons before mgrs before OSDs, one at a time), and doing a host-level dist-upgrade without following that sequence first is a common way to end up with a Ceph cluster that won’t reach quorum. Don’t treat the Proxmox host upgrade and the Ceph upgrade as the same event just because they happen close together.

Actually doing the jump

Once the checklist above is clean, the mechanics are close to the routine process: update the repository lines to point at the new major release’s codename, apt update, apt dist-upgrade, reboot into the new kernel, then rerun pveversion and walk through the cluster/VM list in the web UI to confirm everything that should have survived actually did. Don’t assume the UI looking normal means every guest came back the way it was; spot-check that a couple of VMs still boot and that storage still shows the capacity you expect, especially if a storage backend’s on-disk format changed as part of the release.

The safety net worth having before you start

If your Proxmox host boots from a ZFS root, taking a manual ZFS snapshot of the boot environment immediately before the upgrade gives you a real rollback path that a backup-and-restore doesn’t: boot back into the old snapshot and you’re exactly where you were, no restore process, no downtime beyond a reboot. It’s not a substitute for the VM backups in step one (a snapshot of the host’s root doesn’t protect your guest data if something at the storage layer changes underneath it), but it’s cheap insurance against the single most common failure mode, a major upgrade that boots into a broken state and leaves you stuck mid-migration with no fast way back.

None of this is complicated once you’ve done it once. It’s just unforgiving the first time if you skip the readiness check and find out about an unsupported storage config from a broken boot instead of a warning message. Treat the major-version jump as the one Proxmox maintenance task that earns a deliberate checklist, and the routine point-release updates in between as exactly as boring as they should be.