Prerequisites & Preparation

Complete every item on this page before starting the upgrade on any host. Skipping these checks is the most common cause of a failed upgrade.

NETLAB+ readiness

Warning

Schedule a maintenance window. Do not upgrade while a class or lab reservation is active. Pods should be powered off and there should be no active reservations on the system being serviced.

  • Confirm there are no active or imminent reservations.

  • Take a current backup of your NETLAB+ VM (see Backup NETLAB+ or Backup).

  • Back up any persistent, master, or template pod VMs that you cannot easily rebuild.

Proxmox host readiness

Open a shell on the Proxmox host. In the web UI, navigate to Datacenter > your_server and select Shell (or connect via console/SSH).

Confirm the current version is 8.4.1 or newer:

pveversion

Note

All nodes must be on Proxmox VE 8.4.1+ before upgrading. If you are on an earlier 8.x release, fully update Proxmox VE 8 first with apt update && apt dist-upgrade, then re-check pveversion.

Warning

Use console or IPMI/xClarity access where possible, not just SSH — the network stack and SSH may be interrupted during the upgrade. Ensure at least 5 GB free (ideally 10 GB+) on the root filesystem; check with df -h /.

Run the pve8to9 checklist

Proxmox provides a read-only checklist tool that reports problems to fix before (and after) the upgrade. It makes no changes to your system.

Run the full check and resolve any reported failures or warnings:

pve8to9 --full

Tip

Re-run pve8to9 after fixing each issue, and again after the upgrade, until it reports no remaining problems.

Resolving the systemd-boot warning

On most NETLAB+ hosts, pve8to9 reports the following failure:

FAIL: systemd-boot meta-package installed. This will cause problems on upgrades of
other boot-related packages. Remove 'systemd-boot'

This is expected, and clearing it is safe. Proxmox VE boots via GRUB or via systemd-boot-efi (managed by proxmox-boot-tool) — not by the systemd-boot meta-package. That meta-package is only a transitional package that interferes with boot-related package upgrades, so it should be removed before upgrading. Removing it does not change how your server boots.

Confirm how the node boots:

proxmox-boot-tool status

  • If it errors with /etc/kernel/proxmox-boot-uuids does not exist, the node boots with GRUB (proxmox-boot-tool is not managing the bootloader). This is the common case on NETLAB+ hosts — the systemd-boot packages are unused, so they are safe to remove.

  • If it lists one or more ESPs, the node boots with systemd-boot via proxmox-boot-tool. Only the systemd-boot meta-package is the problem; the actual boot files (systemd-boot-efi / systemd-boot-tools) stay installed.

Remove the meta-package:

apt remove systemd-boot

Warning

Review the package list apt prints before confirming. On a GRUB-booted node it is fine if systemd-boot-efi / systemd-boot-tools are removed along with it (they are unused). On a node that boots with systemd-boot, make sure systemd-boot-efi and systemd-boot-tools remain. Either way, if apt ever proposes removing a kernel or any proxmox-kernel-* package, stop and investigate. See the official systemd-boot upgrade note.

Re-run the checklist and confirm the failure is gone:

pve8to9

Note

Perform this on every node that reports the warning.

Clusters: upgrade one node at a time

Warning

In a cluster, upgrade one node at a time. A cluster can run a mix of 8.4 and 9 nodes during the transition, but avoid configuration changes until all nodes are on the same version.

  • Migrate or power off the VMs on the node you are about to upgrade.

  • Upgrade and reboot that node fully, verify it, then move to the next node.

  • There is no required Proxmox node order. NDG suggests upgrading a host server first to validate the process on a non-critical node, then the rest — and the management server last, so the NETLAB+ appliance (and any infrastructure VMs) stay available until the end.

Ceph

Note

The recommended NETLAB+ design uses direct-attached SSD storage on each host and does not use Ceph, so this step usually does not apply. If you have specifically deployed Ceph, you must upgrade it to the Squid (19.2) release before upgrading Proxmox VE. See the official upgrade guide for the Ceph procedure.