Installing PVE on top of an existing Debian system · Proxmox VE

Proxmox VE is a set of Debian packages. The ISO installer is a convenience that partitions the disks, installs those packages and configures them; it is not a different product. So installing PVE onto a Debian system you already have is a supported path, documented by Proxmox, and it produces a working node.

It is also the path where more goes wrong, because everything the ISO would have decided is now yours to get right — and several of those things are invisible until much later.

When this is the right path

A rented dedicated server. Hetzner, OVH, Scaleway and the rest hand you a machine with Debian already on it and a rescue system, not a console you can boot an ISO from. This is the primary reason the path exists.

A machine you cannot reach physically or out of band. No IPMI, no crash cart, no remote KVM. Converting an already-running Debian install over SSH is possible; booting an ISO is not.

A provider image with mandatory customisation. Some hosts require their own kernel, network configuration or agent. Starting from their Debian image keeps that intact.

And when it is not:

“I already have Debian on this server and reinstalling is inconvenient.” If you can boot an ISO, boot the ISO. The convenience saved is twenty minutes; the cost is every gap in the table below, carried for the life of the node.

“I want a custom partition layout the installer will not do.” The answer file exposes hdsize, swapsize, maxroot, maxvz and minfree, plus full ZFS geometry. Reach for that first.

Prerequisites, in the order they bite

A resolvable, non-loopback hostname

This is the one that produces the most confusing failure. From the documentation: “The hostname of your machine must be resolvable to an IP address. This IP address must not be a loopback one like 127.0.0.1.”

Read-only / Safecheck it before you install anything— Read-only. The address printed must be the machine real address. If it is 127.0.0.1 or 127.0.1.1, fix /etc/hosts before continuing.

hostname
hostname --fqdn
hostname --ip-address
grep -n "$(hostname)" /etc/hosts

Many Debian cloud and provider images ship with the hostname mapped to 127.0.1.1, which is the Debian convention and is wrong for Proxmox. The /etc/hosts line needs the real address:

127.0.0.1       localhost
192.0.2.11      pve01.example.com pve01

::1             localhost ip6-localhost ip6-loopback
ff02::1         ip6-allnodes
ff02::2         ip6-allrouters

Get this wrong and pve-cluster fails to start, producing ipcc_send_rec[1] failed: Connection refused from essentially every pve* command. The message names an IPC failure and says nothing about hostname resolution, which is why people spend an hour on it.

Nothing that rewrites `/etc/resolv.conf`

Packages such as resolvconf can overwrite the file and break DNS after the conversion. Check what manages it before you start, and remove or configure it deliberately.

A backup, or a machine you are willing to lose

This procedure replaces the kernel and reboots. On a remote machine with only a rescue system to fall back on, that reboot is the risk point. Confirm you know how to reach the provider’s rescue mode before you run the reboot, not after.

The procedure

The order matters. Each step assumes the previous one completed.

Configuration changestep 1 — add the Proxmox repository— Writes a deb822 .sources file. Debian 13 Trixie is the correct suite for PVE 9; using bookworm here installs PVE 8 packages onto Trixie and produces an unsupportable mixture.

cat > /etc/apt/sources.list.d/pve-install-repo.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

cat /etc/apt/sources.list.d/pve-install-repo.sources

Configuration changestep 2 — install and verify the repository key— Downloads the archive keyring. Verify the checksum before apt trusts the key: a key fetched over a compromised path signs packages you then install as root.

wget https://enterprise.proxmox.com/debian/proxmox-archive-keyring-trixie.gpg \
-O /usr/share/keyrings/proxmox-archive-keyring.gpg

sha256sum /usr/share/keyrings/proxmox-archive-keyring.gpg
# expect: 136673be77aba35dcce385b28737689ad64fd785a797e57897589aed08db6e45

Compare that hash against the value published on the Proxmox wiki page for this procedure. It is the only integrity check in the whole path, and skipping it means trusting a plain wget to bootstrap the trust that every subsequent package install depends on.

Service impact possiblestep 3 — update and full-upgrade— Brings the existing Debian system current before adding Proxmox packages. Do this as its own step so that any breakage here is attributable to Debian rather than to the conversion.

apt update
apt full-upgrade

Service impact possiblestep 4 — install the Proxmox kernel and reboot into it— Installs the PVE kernel and reboots. This is the risk point on a remote machine: if the new kernel does not boot, recovery is the provider rescue system.

apt install proxmox-default-kernel

systemctl reboot

Read-only / Safestep 5 — confirm you are on the Proxmox kernel— Read-only. Do not continue until uname -r reports a -pve kernel. Installing proxmox-ve while running the Debian kernel is the ordering mistake that produces a half-converted system.

uname -r

Service impact possiblestep 6 — install Proxmox VE— Installs the platform. postfix prompts for a mail configuration; choose Local only unless you have a relay to point at. open-iscsi and chrony are part of the documented set.

apt install proxmox-ve postfix open-iscsi chrony

Service impact possiblestep 7 — remove the Debian kernel and os-prober— Removes the Debian kernel so the machine cannot boot back into a non-PVE kernel, and os-prober, which would add guest disks it finds to the boot menu.

apt remove linux-image-amd64 'linux-image-6.12*'
update-grub

apt remove os-prober

os-prober scans block devices for other operating systems and adds entries to the GRUB menu. On a hypervisor those block devices are VM disks, so it can add boot entries for your guests’ operating systems to the host’s boot menu — which is confusing at best and, on a shared machine, an information disclosure about what is running.

Verifying the result

Read-only / Safedoes this look like a Proxmox node?— Read-only. Version, services and the API socket. pveversion --verbose lists the component versions and is the artefact to compare against an ISO-installed node.

pveversion --verbose
systemctl status pve-cluster pvedaemon pveproxy pvestatd --no-pager
ss -tlnp | grep -E ':8006|:3128'

The GUI should answer on port 8006. If pve-cluster is not running, the hostname resolution check from the prerequisites is the first thing to revisit.

What the ISO would have done that this did not

This is the part that matters six months later.

Area	ISO installer	This path
Root filesystem	ZFS mirror, or LVM with a sized data volume	Whatever Debian or the provider chose — often a single ext4 partition
Boot redundancy	An ESP on every selected disk, in the synced set	One ESP, on one disk
`local-lvm` thin pool	Created and registered as PVE storage	Absent; guest storage must be configured by hand
Swap sizing	Sized against RAM, clamped to 4–8 GiB	Provider default, frequently a large swap file
Network	A `vmbr0` bridge with the management address on it	The provider’s flat interface configuration; no bridge
Repository set	Enterprise repository configured	No-subscription, from step 1
Kernel	PVE kernel only, from the start	PVE kernel added, Debian kernel removed by hand
Time sync	chrony	Whatever the image had, until step 6

Two of those rows are the ones that actually cause incidents.

No vmbr0. Guests need a bridge. The provider’s configuration has the address on a physical interface, and converting that to a bridge is the step where you lose the network if you get it wrong — on a machine whose recovery path is a rescue system. Do it with a rollback timer and read the networking part of this course first; several providers also require MAC-address restrictions that make the naive bridge configuration fail in provider-specific ways.

No local-lvm. A default Debian layout gives the root filesystem the whole disk, so there is no volume group space for a thin pool. You either plan the partitioning before the conversion, or you accept directory storage on the root filesystem, which is a real choice with real consequences — no thin provisioning, no LVM snapshots, and a full root filesystem taking the host down rather than just the guest.

Under the hood

Why proxmox-ve is a metapackage, and what the kernel ordering is protecting.

proxmox-ve depends on the pieces rather than containing them: pve-manager (the GUI and the pve* tools), qemu-server, pve-container, pve-cluster (pmxcfs), libpve-* libraries, and a kernel metapackage. Installing it pulls the platform in as a dependency graph, which is why the conversion is genuinely a package operation rather than an installer in disguise.

The kernel ordering in steps 4 to 7 is protecting two things.

The Proxmox kernel carries what KVM and ZFS need. It is a Ubuntu-based kernel with the ZFS modules and the virtualisation configuration Proxmox depends on, rather than the stock Debian kernel. Installing proxmox-ve while running the Debian kernel produces a system whose packages are present and whose modules are not, and the symptoms — guests that will not start, ZFS pools that cannot import — do not obviously point at the kernel.

Removing the Debian kernel prevents a silent regression. Leave linux-image-amd64 installed and a future Debian kernel upgrade can become the default boot entry. The node reboots months later during unrelated maintenance, comes up on the Debian kernel, and everything virtualisation-related fails at once on a machine nobody changed. That is why step 7 exists and why update-grub follows it.

Two structural differences from an ISO install persist afterwards.

The repository set. Step 1 configures pve-no-subscription, because the enterprise repository requires a subscription key. A production node should be moved to pve-enterprise once it has one — the packages are the same code with more soak, and the choice is about how quickly changes reach you.

pmxcfs is a filesystem that must mount at boot. pve-cluster provides /etc/pve as a FUSE mount, and it refuses to start when the hostname does not resolve to a real address, because a node’s identity in a cluster is that hostname. On an ISO install the installer guarantees this. On this path it is your /etc/hosts file, which is why the prerequisite check is first and why its failure mode — ipcc_send_rec[1] failed: Connection refused from every pve* command — is worth recognising on sight.

What happens if you convert a rented dedicated server and lose the network?

You lose the machine until the provider’s rescue system gets you back, which is minutes if you have used it before and considerably longer if you have not.

The two steps that cause it are the reboot in step 4 and the later conversion of the provider’s interface configuration into a vmbr0 bridge.

The reboot. The machine comes up on a new kernel with different network drivers and, potentially, different interface names. Predictable interface naming usually holds, but a provider image using a provider-specific driver may not have an equivalent in the PVE kernel at all. Before rebooting, record what you would need to know from a rescue shell: the interface name, the address, the gateway, and the contents of /etc/network/interfaces. Save that off the machine.

The bridge conversion. This is where most people actually lose access. Moving the address from enp1s0 to vmbr0 is a routine change in a datacenter and a hazardous one at a hosting provider, because many of them filter by MAC address on the switch port. A bridge that presents a guest MAC on the uplink gets that traffic dropped, and some providers disable the port entirely. The provider-specific documentation for Proxmox networking is not optional reading, and routed rather than bridged configurations are common there for exactly this reason.

The control that helps in both cases is the same one from the firewall lesson: schedule the undo before you make the change.

IFACE_CFG=/etc/network/interfaces
cp "$IFACE_CFG" /root/interfaces.known-good
echo "cp /root/interfaces.known-good $IFACE_CFG && systemctl reboot" \
  | at now + 15 minutes

If you are still connected in fifteen minutes, atrm the job. If you are not, the machine restores itself and reboots while you are still working out what went wrong — which turns a rescue-system ticket into a fifteen-minute wait.

Before any of this, confirm the rescue path works. Boot the provider’s rescue system once, deliberately, while nothing is wrong, and confirm you can reach the disks and mount the root filesystem. A rescue system you have never used is not a recovery plan, and the conversion of a remote machine is precisely the operation that assumes you have one.

Common mistakes

Hostname resolving to 127.0.1.1. pve-cluster will not start and every pve* command reports an IPC failure that names nothing useful.
Using the bookworm suite. That is PVE 8 on a Trixie system. Debian 13 needs trixie.
Skipping the keyring checksum. It is the only integrity check in the procedure.
Installing proxmox-ve before rebooting into the PVE kernel. Packages present, modules absent, symptoms that point elsewhere.
Leaving linux-image-amd64 installed. A future Debian kernel becomes the default and the node breaks during unrelated maintenance.
Leaving os-prober. It adds your guests’ operating systems to the host boot menu.
Converting to vmbr0 without reading the provider’s networking notes. MAC filtering on the uplink drops bridged guest traffic.
Not planning storage before the conversion. Repartitioning under a running hypervisor is much harder than choosing a layout beforehand.

Key takeaways

PVE on Debian is supported and produces a working node. Use it for rented servers and machines you cannot boot an ISO on, not for convenience.
The hostname must resolve to a real, non-loopback address before anything else. The failure mode names IPC, not DNS.
Suite is trixie for PVE 9. Verify the keyring checksum.
Install the PVE kernel, reboot, confirm uname -r, then install proxmox-ve. The order is what makes the modules match the packages.
Remove linux-image-amd64 and os-prober afterwards.
The ISO would have given you a bridge, a thin pool, boot redundancy and a sized root layout. None of those arrive on this path.
On a remote machine, verify the rescue system and schedule the undo before any network change.

Knowledge check

Why this matters

This path exists because a large share of Proxmox deployments are on rented hardware where booting an ISO is not an option. Dismissing it as unsupported would be wrong — Proxmox documents it, and it produces a node that works.

What is worth being precise about is what the ISO installer actually is. It is not a wrapper around apt install proxmox-ve. It is a set of decisions: a root layout with redundancy, an ESP per disk in a synced set, a sized thin pool for guests, a bridge for guest networking, and a swap size chosen for a hypervisor rather than for a general-purpose server. Every one of those is a decision the conversion hands back to you, and none of them announces itself.

That is why the honest failure mode of this path is not a failed install. It is a node that works perfectly and is quietly different from its neighbours — one bootable disk instead of two, guests on directory storage instead of a thin pool, a root filesystem that fills and takes the host down rather than one guest. Those differences surface as incidents attributed to something else entirely, months later, on the one node that was built differently.

So the rule is simple. Use this path when you have no alternative, and then close the gaps deliberately: read the table, decide each row, and record what you chose. And when you do have the choice, boot the ISO or write an answer file — because the twenty minutes it saves is the least valuable thing about it.