1. Introduction

This document describes the manual in-place upgrade process for Proxmox VE using apt.

Scope: PVE 7 → 8, then PVE 8 → 9

Philosophy:

  • No script magic - you execute each command and understand what it does

  • The pve7to8 and pve8to9 checklist tools are your safety net - run them before AND after major steps

  • Known issues are documented where they occur, not buried at the end

Caution
 These upgrades change the underlying Debian distribution (Bullseye → Bookworm → Trixie). This is a significant operation. Take it seriously.

2. General Prerequisites

Before starting ANY upgrade, ensure:

  • ❏ Tested backups of all VMs, containers, and host configurations

  • ❏ Console/IPMI access - never rely solely on SSH during upgrades

  • ❏ Minimum 5GB free disk space on root mount (10GB+ recommended)

  • ❏ Healthy cluster state - all nodes online and communicating

  • ❏ Critical workloads migrated away from the node being upgraded

  • ❏ Time and focus - do not rush, do not multitask

3. Upgrade from PVE 7 to PVE 8

3.1. Phase 1: Get the Checklist Tool

The pve7to8 checklist tool is included in PVE 7.4-15 and later. You must upgrade to this version first.

apt update
apt dist-upgrade
pveversion

Verify output shows pve-manager/7.4-15 or higher. If not, repeat until you reach 7.4-15+.

3.2. Phase 2: Run Checklist and Resolve Issues

Run the checklist with full checks enabled:

pve7to8 --full

This tool identifies problems but does NOT fix them automatically. You must resolve each warning before proceeding.

Common issues at this stage:

  • Pending reboot required

  • Outdated package versions

  • Ceph not on Quincy 17.2 (required for hyper-converged setups)

  • Corosync configuration issues in clusters

Important
 Do not proceed until pve7to8 --full reports no critical warnings.

3.3. Phase 3: Update APT Repositories

3.3.1. Update Debian Base Repository

Change from Bullseye to Bookworm:

sed -i 's/bullseye/bookworm/g' /etc/apt/sources.list

Verify the file looks correct:

cat /etc/apt/sources.list

Expected content (non-free-firmware is new in Bookworm):

deb http://ftp.debian.org/debian bookworm main contrib non-free non-free-firmware
deb http://ftp.debian.org/debian bookworm-updates main contrib non-free non-free-firmware
deb http://security.debian.org bookworm-security main contrib non-free non-free-firmware

3.3.2. Update Proxmox VE Repository

For enterprise subscription:

echo "deb https://enterprise.proxmox.com/debian/pve bookworm pve-enterprise" > /etc/apt/sources.list.d/pve-enterprise.list

For no-subscription (testing/home use):

echo "deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription" > /etc/apt/sources.list.d/pve-no-subscription.list

Remove any old repository files that still reference bullseye:

ls -la /etc/apt/sources.list.d/
# Review and edit/remove files still pointing to bullseye

3.3.3. Update Ceph Repository (Hyper-Converged Only)

Important
 Ceph must already be running Quincy 17.2 before upgrading PVE. Upgrade Ceph first if needed.

For enterprise:

echo "deb https://enterprise.proxmox.com/debian/ceph-quincy bookworm enterprise" > /etc/apt/sources.list.d/ceph.list

For no-subscription:

echo "deb http://download.proxmox.com/debian/ceph-quincy bookworm no-subscription" > /etc/apt/sources.list.d/ceph.list

3.3.4. Known Issue: Network Interface Name Changes

Warning
 The kernel upgrade may cause network interface names to change (e.g., eth0 becomes enp3s0). Ensure you have IPMI/console access before proceeding. If you lose network after reboot, you will need console access to fix /etc/network/interfaces.

3.4. Phase 4: Perform the Upgrade

3.4.1. Refresh Package Index

apt update

If you see errors about missing repositories, go back and fix your sources.list files.

3.4.2. Known Issue: Package Conflict with proxmox-ve

The upgrade may fail if linux-image-amd64 conflicts with proxmox-ve. Remove it first:

apt remove linux-image-amd64

This removes the Debian kernel meta-package. PVE uses its own kernel (pve-kernel).

3.4.3. Known Issue: GRUB on UEFI with LVM Root

If your system boots via UEFI and uses LVM for root, install the UEFI grub package before upgrading:

[ -d /sys/firmware/efi ] && apt install grub-efi-amd64

3.4.4. Run the Distribution Upgrade

Important
 Run this from console/IPMI, not SSH. SSH connections may drop during the upgrade. 
apt dist-upgrade

This will take 5-60+ minutes depending on disk speed.

3.4.5. Configuration File Prompts

During upgrade, you will be asked about configuration files. Recommended responses:

File Recommended Notes

/etc/issue

No (keep current)

Cosmetic only, auto-regenerated

/etc/lvm/lvm.conf

Yes (install maintainer’s)

Unless you have custom LVM settings

/etc/ssh/sshd_config

Yes (install maintainer’s)

Unless you have custom SSH settings

/etc/default/grub

No (keep current)

Unless you have NO custom kernel parameters

3.5. Phase 5: Verify and Reboot

3.5.1. Re-run Checklist

pve7to8

Address any new warnings.

3.5.2. Reboot

reboot

You MUST reboot even if you were already running a 6.x kernel. The new userspace requires the new kernel ABI.

3.5.3. Known Issue: Network Hangs on Boot (NTPsec)

If the system hangs during boot waiting for network time sync, NTPsec is the cause.

Fix Option 1 - Switch to chrony (recommended):

apt install chrony

Fix Option 2 - Disable ntpsec-ntpdate:

apt remove ntpsec-ntpdate

If already stuck at boot: Boot into recovery mode and run:

chmod -x /etc/network/if-up.d/ntpsec-ntpdate

3.5.4. Known Issue: ZFS on UEFI Systems

If you boot from ZFS on UEFI, install systemd-boot after the upgrade:

apt install systemd-boot
proxmox-boot-tool status

3.6. Phase 6: Post-Upgrade Tasks

  • Clear browser cache and force-reload the web GUI (Ctrl+Shift+R, or Cmd+Alt+R on macOS)

  • Verify pveversion shows 8.x

  • In clusters: proceed with next node only after confirming this node is healthy

4. Upgrade from PVE 8 to PVE 9

4.1. Phase 1: Get the Checklist Tool

The pve8to9 checklist tool is included in PVE 8.4.1 and later. You must upgrade to this version first.

apt update
apt dist-upgrade
pveversion

Verify output shows pve-manager/8.4.1 or higher.

4.2. Phase 2: Run Checklist and Resolve Issues

Run the checklist with full checks enabled:

pve8to9 --full

4.2.1. Firmware Warning

Debian 12 (Bookworm) moved firmware from the non-free component to a new non-free-firmware component. You must add this to your sources to resolve the "missing microcode" warning.

1. Edit Sources List

Open the configuration file:

nano /etc/apt/sources.list

Append non-free-firmware to the end of your Debian repository lines.

2. Update and Install

Refresh the package list and install the microcode package matching your CPU:

apt update

# For Intel CPUs (fixes your specific warning)
apt install intel-microcode

# For AMD CPUs
apt install amd64-microcode
3. Verify

After installation, you should see update-initramfs running in the output, which ensures the microcode is loaded at the next boot.

4.2.2. Known Issue: LVM Autoactivation Migration

If pve8to9 warns about LVM autoactivation, run the migration script:

/usr/share/pve-manager/migrations/pve-lvm-disable-autoactivation

4.2.3. Known Issue: systemd-boot Meta-Package

If pve8to9 suggests removing the systemd-boot meta-package (and you did not manually configure systemd-boot):

apt remove systemd-boot

4.2.4. Known Issue: Kernel Audit Messages

To avoid noisy audit messages during upgrade, disable the audit socket:

systemctl disable --now systemd-journald-audit.socket
Important
 Do not proceed until pve8to9 --full reports no critical warnings.

4.3. Phase 3: Update APT Repositories

4.3.1. Update Debian Base Repository

Change from Bookworm to Trixie:

sed -i 's/bookworm/trixie/g' /etc/apt/sources.list

Verify the result:

cat /etc/apt/sources.list

4.3.2. Update Proxmox VE Repository

For PVE 9, you can use the new deb822 format (recommended) or classic format.

Best is to run sources udpate tool (might be only accessible after update but thats ok)

apt modernize-sources

Manual - New deb822 format (enterprise):

cat > /etc/apt/sources.list.d/pve-enterprise.sources << 'EOF'
Types: deb
URIs: https://enterprise.proxmox.com/debian/pve
Suites: trixie
Components: pve-enterprise
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

Remove the old .list file if it exists:

rm -f /etc/apt/sources.list.d/pve-enterprise.list

Manual - New deb822 format (no-subscription):

cat > /etc/apt/sources.list.d/pve-no-subscription.sources << 'EOF'
Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

Manual - Classic format:

sed -i 's/bookworm/trixie/g' /etc/apt/sources.list.d/pve-enterprise.list
# or
sed -i 's/bookworm/trixie/g' /etc/apt/sources.list.d/pve-no-subscription.list

4.3.3. Update Ceph Repository (Hyper-Converged Only)

Important
 Ceph must be running Squid 19.2 before upgrading to PVE 9.

For enterprise:

echo "deb https://enterprise.proxmox.com/debian/ceph-squid trixie enterprise" > /etc/apt/sources.list.d/ceph.list

For no-subscription:

echo "deb http://download.proxmox.com/debian/ceph-squid trixie no-subscription" > /etc/apt/sources.list.d/ceph.list

4.3.4. Known Issue: Network Interface Name Changes

Same as PVE 7→8. Interface names may change. Have console access ready.

You can use the pinning tool after upgrade if names change:

pve-network-interface-pinning

4.4. Phase 4: Perform the Upgrade

4.4.1. Refresh Package Index

apt update

4.4.2. Known Issue: Package Conflict with proxmox-ve

Same as PVE 7→8. Remove conflicting package first:

apt remove linux-image-amd64

4.4.3. Known Issue: GRUB on UEFI with LVM Root

Same as PVE 7→8:

[ -d /sys/firmware/efi ] && apt install grub-efi-amd64

4.4.4. Run the Distribution Upgrade

Important
 Run this from console/IPMI, not SSH. 
apt dist-upgrade

4.4.5. Known Issue: LVM Thin Pool Check Failure

If you see "Check of pool pve/data failed" during upgrade:

lvconvert --repair pve/data

4.4.6. Known Issue: Ceph Full Mesh Network Restart

If using Ceph with FRR for full mesh networking, update /etc/network/interfaces to include:

post-up /usr/bin/systemctl is-active --quiet frr.service && /usr/bin/systemctl restart frr.service || true

4.4.7. Configuration File Prompts

File Recommended Notes

/etc/issue

No (keep current)

Auto-regenerated

/etc/lvm/lvm.conf

Yes (install maintainer’s)

Unless custom LVM settings

/etc/ssh/sshd_config

Yes (install maintainer’s)

Unless custom SSH settings

/etc/default/grub

No (keep current)

Unless no custom parameters

/etc/chrony/chrony.conf

Yes (install maintainer’s)

Unless custom NTP settings

4.5. Phase 5: Verify and Reboot

4.5.1. Check apt status

if its still running want to check the logs, look here:

tail -f /var/log/apt/term.log
# Ctrl + C to quit

if you lost access /track of the process or you might have missed a question to answer

sudo fuser -vki -TERM /var/lib/dpkg/lock /var/lib/dpkg/lock-frontend
sudo dpkg --configure --pending

4.5.2. Re-run Checklist

pve8to9

4.5.3. Reboot

It will warn you that APT is still running when its not done yet.

reboot

4.6. Phase 6: Post-Upgrade Tasks

  • Clear browser cache and force-reload web GUI

  • Verify pveversion shows 9.x

  • In clusters: HA groups are automatically migrated to HA rules

  • Optional: modernize apt sources with apt modernize-sources

5. Additional Considerations

5.1. NVIDIA vGPU Compatibility

PVE Version Minimum NVIDIA GRID Version

PVE 8

GRID 16.0+ (driver 535.54.06+)

PVE 9

GRID 18.3+ (driver 570.158.02+)

Upgrade NVIDIA drivers BEFORE upgrading PVE.

5.2. cgroupv2 Migration

PVE 8 deprecated cgroup v1. PVE 9 removes support entirely.

Containers running systemd older than version 230 (released 2016) will NOT work on PVE 9. Plan migration during PVE 8 lifecycle.

5.3. VM Live Migration

  • Always test migrations with non-production VMs first

  • CPU heterogeneity in clusters causes problems

  • Intel Skylake+ CPUs: target host needs kernel 6.2.16-5+ for restricted CPU types

5.4. PCI Passthrough on PVE 9

Kernel 6.14 may break some VMs using PCI passthrough. If affected, pin to pve-kernel 9.2+pve1 or newer.

5.5. Veeam Backup Compatibility

Veeam is incompatible with QEMU 10.0+ in PVE 9. Pin to pve-qemu 9.2+pve1 until Veeam releases a fix.

5.6. Clustered Environments

  • Upgrade one node at a time

  • Migration from older PVE to newer PVE works

  • Migration from newer PVE to older PVE does NOT work

  • Do not upgrade all nodes simultaneously

  • Verify cluster health after each node upgrade before proceeding

6. References