Proxmox System Update

The official Proxmox recommendation

Proxmox's own upgrade guidance for a running host (within the same major version) is to run:

apt update && apt full-upgrade -y

That one line is the official command on any current Proxmox release. The hard part isn't the upgrade itself; it's making sure the repositories are clean, the right ones are enabled, and the host is in a sensible state afterwards.

What ProxMenux runs on top — verified against the script

This option runs exactly the apt command above, wrapped with the repo hygiene, DKMS rebuild for ProxMenux-managed drivers and post-upgrade cleanup the official upgrade guide also recommends. Everything below maps 1:1 to scripts/utilities/proxmox_update.sh and the single safe worker scripts/global/update-pve-safe.sh — nothing implied, every step is in the code:

• Detects the PVE major version from inside the worker (pveversion | grep -oP 'pve-manager/\K[0-9]+') and adapts the base Proxmox / Debian repo URLs (bookworm on PVE 8, trixie on PVE 9). There is no fan-out to per-version worker scripts — a single safe worker handles both.
• Cleans up repositories in a conservative way. ensure_repositories runs first but only when the base Proxmox / Debian sources are missing — a bare host gets them written, a configured host is a no-op. cleanup_duplicate_repos then removes exact URL + Suite + Component duplicates only against proxmox.sources / debian.sources; user-authored files (enterprise, Ceph, alternative NTP mirrors, custom download.proxmox.com/* entries or hand-written pve-*.list) are left untouched, and every file is backed up before being edited.
• Runs the upgrade non-interactively with DEBIAN_FRONTEND=noninteractive and --force-confdef --force-confold — if a configuration file you already modified also changed upstream, your version stays in place. No silent overwrites of custom configs.
• Skips forcing optional utilities. The safe worker does not push zfsutils-linux, chrony, ifupdown2 or similar packages onto the host — a Proxmox install that opted out of any of them keeps its choice. Missing packages are surfaced by the higher-level installer flows, not by the update path.
• LVM metadata sanity check against stray PV headers from passthrough disks (warn-only, no automatic fix).
• Cleans up afterwards: apt-get autoremove -y + apt-get autoclean -y.
• DKMS rebuild before the reboot prompt. When the upgrade staged a new kernel, the wrapper calls pmx_rebuild_dkms_after_kernel to rebuild every driver that ProxMenux installed via DKMS against the incoming kernel version — so the modules are ready before the box comes back up. Reboot detection uses /var/run/reboot-required when needrestart is present, and falls back to a dpkg-query comparison between the running kernel and the newest installed proxmox-kernel-*-pve-signed / pve-kernel-*-pve package when it isn't — a signal that survives the many Proxmox hosts that ship without needrestart.

Confirmation dialog

Selecting the option opens a summary of what the worker will do, requiring an explicit confirmation:

How the wrapper routes

What the worker does

A single worker (scripts/global/update-pve-safe.sh) handles both PVE 8 and PVE 9. It detects the major version internally and uses the version-appropriate codename (bookworm or trixie) for its base sources. The stages are:

1. Sanity checks. Verifies at least ~1 GB free in /var/cache/apt/archives and pings download.proxmox.com. Aborts early with a clear message when either fails, so the run doesn't die in the middle of an apt transaction.
2. Repo bootstrap. ensure_repositories writes the base Proxmox / Debian sources only when they are missing (a fresh or hand-cleaned host); on a configured host it does nothing.
3. Apt update with GPG auto-recovery. On NO_PUBKEY for any repo (yours or a third-party one) the worker imports the missing key and retries automatically before failing.
4. Conservative duplicate cleanup. cleanup_duplicate_repos only removes exact URL + Suite + Component matches against proxmox.sources / debian.sources. User-authored files — enterprise, Ceph, alternative NTP mirrors, custom download.proxmox.com/* entries, hand-written pve-*.list — are left intact. Every file is backed up before modification.
5. Pending upgrades + security count. Reports how many packages will change and how many of those come from the security suite, so the confirmation dialog has real numbers to show.
6. Confirmation dialog. The wrapper asks for an explicit yes before touching apt.
7. apt full-upgrade. Runs with DEBIAN_FRONTEND=noninteractive and --force-confdef --force-confold so any configuration file you customised keeps its current contents when upstream also changed it. Never overwrites operator-edited configs silently.
8. LVM sanity check. lvm_repair_check refreshes VG metadata when disks passed through to guest VMs (DSM, TrueNAS, storage appliances) come back with old PV headers.
9. DKMS rebuild for ProxMenux-managed drivers. When the upgrade staged a new kernel, pmx_rebuild_dkms_after_kernel reads components_status.json for the drivers ProxMenux installed (currently nvidia_driver → module nvidia, coral_driver → module gasket), installs the matching kernel headers (proxmox-headers-<newkver> when available, else pve-headers-<newkver>) and runs dkms autoinstall -k <newkver>. If dkms status then doesn't show the modules built against the new kernel, the worker falls back to re-running each installer with --auto-reinstall. Any failure is logged but does not abort the update — you land on the reboot prompt in every case.
10. Post-cleanup. apt-get autoremove + apt-get autoclean before returning control to the wrapper.

Post-update cleanup & reboot

After the worker exits, the wrapper runs:

apt-get autoremove -y    # drop unused dependencies pulled in by old packages
apt-get autoclean        # drop downloaded .deb files no longer in the index

Then it checks whether a reboot is needed. Two signals trigger the prompt:

• /var/run/reboot-required exists (created by the kernel package post-install hook)
• The update log contains linux-image entries (kernel was actually upgraded)

If either is true, a whiptail dialog asks "Some changes require a reboot to take effect. Do you want to restart now?". Decline to keep running on the old kernel until you choose to reboot manually (e.g. during a planned maintenance window).

What you see at the end

When the worker finishes, the terminal shows the cleanup output and (if the kernel changed) the reboot prompt:

How the safe worker treats the enterprise repo

docs.utils.systemUpdate.noSub.intro

1. docs.utils.systemUpdate.noSub.items.0
2. docs.utils.systemUpdate.noSub.items.1
3. The enterprise pve-enterprise.sources / ceph.sources files are never modified by the update path. The removal of the enterprise repo when it's unwanted is handled elsewhere in ProxMenux (the Automated post-install script), not here.

If you have a paid subscription, keep <code>pve-enterprise.sources</code> enabled and the safe worker will let it drive the upgrade unchanged. If you don't, either run the Automated post-install first (it does the switch and records it) or comment the enterprise source out manually — the update path will not do it for you.

Cluster considerations

What it doesn't do

• Major-version upgrade. 8 → 9 is a separate operation — see Upgrade PVE 8 to PVE 9.
• Backup. No snapshots, no rollback. Apt operations are not transactional. Combine with your normal backup discipline (PBS, vzdump, ZFS snapshots).
• Container / VM updates. Only the host is upgraded; guests are left alone.
• Firmware updates. CPU microcode, NIC firmware, BIOS — out of scope.

Troubleshooting

Files involved

scripts/utilities/proxmox_update.sh              # this script (wrapper)
scripts/global/update-pve-safe.sh                # single safe worker (PVE 8 + PVE 9)
scripts/global/common-functions.sh               # cleanup_duplicate_repos used by the worker
scripts/global/utils-install-functions.sh        # ensure_repositories + pmx_rebuild_dkms_after_kernel
/usr/local/share/proxmenux/components_status.json # ProxMenux-managed DKMS driver registry
/etc/apt/sources.list.d/proxmox.sources          # deb822 no-subscription source (bare-host bootstrap)
/etc/apt/sources.list.d/debian.sources           # deb822 Debian sources (bare-host bootstrap)
/var/run/reboot-required                         # read to decide on reboot prompt
# Reboot fallback when needrestart isn't installed:
# dpkg-query -W 'proxmox-kernel-*-pve-signed' 'pve-kernel-*-pve' vs. uname -r

Related

• Upgrade PVE 8 to PVE 9 — for the major-version upgrade (different tool, different safety model).
• System Utilities Installer — to install the CLI tools you want around updates (htop / btop / ncdu).
• Utilities overview — back to the section overview.