Skip to content

Proxmox Update Workflow

Standard operating procedure for updating the Proxmox VE host and its guest VMs/LXCs.

Part 1: Updating the Proxmox Host (PVE)

Step 1 — Check Available Updates

SSH into the PVE host or use the web UI shell.

apt update && apt list --upgradable

Scan the list for kernel updates (proxmox-kernel-*) — these require a reboot. All other updates are typically live-safe.

Check the forum before big updates

Check the Proxmox forum before proceeding if a lot of updates have accumulated or a version number looks like a major bump.

Step 2 — Back Up Host Config with vzdump

Run this before every update batch. Takes under a minute.

tar --zstd -cf /var/lib/vz/dump/pve-host-config-$(date +%Y%m%d).tar.zst \
  /etc/pve \
  /etc/network/interfaces \
  /etc/hosts \
  /etc/hostname \
  /etc/resolv.conf \
  /root

This saves /etc/pve, network config, VM/LXC definitions, storage config, users and ACLs. It does not save the full OS — see restore notes below.

Note your current kernel version in case you need to fall back:

uname -r

Step 3 — Apply Host Updates

Always use dist-upgrade, not plain upgrade:

apt dist-upgrade

Use dist-upgrade, not upgrade

Plain apt upgrade can leave PVE packages in broken half-states due to dependency changes between Proxmox packages.

Step 4 — Schedule Reboot (if Kernel Updated)

If a kernel update was included, a reboot is required to activate it. The update itself installs safely with guests running — only the reboot causes a downtime window.

Check which guests are set to autostart:

grep -r "onboot: 1" /etc/pve/lxc/ /etc/pve/qemu-server/

Before rebooting, gracefully shut down any sensitive guests (see Part 2 below). Guests with onboot: 1 will restart automatically after the host comes back up.

# When ready to reboot
shutdown -r now
# or schedule it
shutdown -r 02:00 "Proxmox kernel update reboot"

After reboot, verify the system came up cleanly:

pveversion -v
zpool status          # if using ZFS anywhere
pct list && qm list   # confirm guests came back up

Restoring Host Config from vzdump (If Needed)

When to use this

Use this if an update breaks PVE config, storage definitions, or VM settings. If the OS itself won't boot, reinstall PVE from ISO first, then follow these steps.

# Extract the archive (adjust filename/date)
tar --zstd -xf /var/lib/vz/dump/pve-host-config-YYYYMMDD.tar.zst -C /

# Restart the cluster filesystem to pick up restored config
systemctl restart pve-cluster

For a targeted restore (e.g. just /etc/pve):

tar --zstd -xf pve-host-config-YYYYMMDD.tar.zst etc/pve -C /
systemctl restart pve-cluster

Verify in the web UI that VMs, storage, and users look correct after restoring.

Part 2: Updating VMs and LXCs

Update the host first

Update the host first and confirm it's healthy before updating guests.

Example A — Immich (Docker-based LXC or VM)

Immich runs Postgres and background ML workers, so it needs a careful shutdown order before any reboot.

Checking for Updates

If using Docker Compose, check for new image versions:

cd /path/to/immich/
docker compose pull   # pulls latest images, does not restart yet

Review the Immich release notes for any breaking changes or migration steps before applying.

Applying Updates

docker compose pull
docker compose up -d   # recreates containers with new images
docker compose logs -f # watch for errors on startup

Graceful Shutdown Before Host Reboot

Stop services in this order — ML jobs first, database last:

# Shell into the LXC/VM
pct enter <vmid>   # or ssh in

cd /path/to/immich/

# Graceful compose stop (honours stop_grace_period, does not remove containers)
docker compose stop

# Verify everything is down
docker ps

Then from the PVE host:

pct shutdown <vmid>   # or qm shutdown <vmid> for a VM

shutdown vs stop

Use shutdown, not stop — stop is a hard kill with no graceful shutdown.

After the host reboots and the guest autostart brings it back up:

pct enter <vmid>
cd /path/to/immich/
docker compose up -d
docker compose logs -f

Example B — Jellyfin (LXC, systemd service)

Jellyfin uses SQLite which is crash-resilient, making this simpler than Immich. Still worth a clean stop before a host reboot.

Checking for Updates

# Shell into the Jellyfin LXC
pct enter <vmid>

apt update && apt list --upgradable

Applying Updates

apt dist-upgrade

Jellyfin updates via apt cleanly with no special ordering needed. The service restarts automatically after the package update.

Graceful Shutdown Before Host Reboot

pct enter <vmid>
systemctl stop jellyfin
exit

# Then from PVE host
pct shutdown <vmid>

No special ordering needed — stopping the service before shutdown is sufficient.

After host reboots and the LXC comes back up (autostart), Jellyfin should be running:

pct enter <vmid>
systemctl status jellyfin

Quick Reference Checklist

Before Every Update

  • [ ] apt update && apt list --upgradable — check what's pending
  • [ ] Check Proxmox forum if major version bump or lots of accumulated updates
  • [ ] tar --zstd -cf /var/lib/vz/dump/pve-host-config-$(date +%Y%m%d).tar.zst /etc/pve /etc/network/interfaces /etc/hosts /root — back up host config
  • [ ] Note current kernel: uname -r

Applying Updates

  • [ ] apt dist-upgrade — update host packages
  • [ ] If kernel updated: plan reboot window, shut down sensitive guests first

Shutting Down Guests (Pre-Reboot)

  • [ ] Immich: docker compose stop inside the LXC, then pct shutdown <vmid>
  • [ ] Jellyfin: systemctl stop jellyfin inside the LXC, then pct shutdown <vmid>
  • [ ] Confirm autostart is enabled on guests so they come back up automatically

After Reboot

  • [ ] pveversion -v — confirm PVE came up correctly
  • [ ] pct list && qm list — confirm guests are running
  • [ ] Check Immich and Jellyfin are healthy in their respective UIs