Upgrade Proxmox VE to a new major version safely

A Proxmox major upgrade (for example from 7 to 8, or 8 to 9) also upgrades the underlying Debian release. It is well documented and usually smooth, but it touches the kernel, cluster stack and storage, so preparation matters more than speed.

Before you start

• Read the official Proxmox upgrade guide for your exact versions; it lists known issues and required steps.
• Fresh, tested backups of all VMs and containers (PBS or vzdump).
• The current version fully updated first: apt update && apt full-upgrade.
• Console or IPMI access, and a maintenance window.
• In clusters: all nodes healthy (pvecm status) and Ceph healthy if used.

Run the upgrade checker

Each major upgrade comes with a checker script named after the versions, such as pve8to9. Run it with all checks:

pve8to9 --full

Fix every FAIL and review every WARN, then run it again until it is clean. Use the script name that matches your upgrade path.

Move guests off the node

In a cluster, migrate VMs to other nodes (migrate VMs) or shut them down. On a single host, shut down guests before the upgrade.

Switch repositories

1. Update the Debian sources to the new codename as the upgrade guide describes.
2. Update the Proxmox repository (enterprise or no-subscription) to the new codename, and the Ceph repository if used.
3. Make sure no old or third-party repositories point to the previous release.

Upgrade the node

apt update

apt dist-upgrade

Answer configuration prompts carefully; the upgrade guide says which files to keep. When it finishes, reboot into the new kernel.

Verify and continue

• pveversion shows the new version and the web UI loads.
• Start a test VM and check storage and networking.
• In clusters, confirm the node rejoins with pvecm status, then repeat on the next node.

Troubleshooting

• Network interface names changed: fix /etc/network/interfaces from the console.
• Held or broken packages: a leftover repository for the old release; remove it and run apt -f install.
• Cluster nodes on different versions: mixed versions are fine briefly during the upgrade, but finish all nodes promptly.

Frequently asked questions

Can I skip a major version?

No. Upgrade one major version at a time.

Is a fresh install better?

Sometimes, for old or messy hosts; restore guests from backups onto the new install.

How long does it take?

Often under an hour per node, plus migration time for guests.

Next steps

• Repositories and updates
• Cluster setup
• Troubleshooting