How to Install Proxmox VE: Step-by-Step Install Guide

Installing Proxmox VE is a short process wrapped around four decisions that are annoying to undo:

• Boot mode — install in UEFI mode unless the hardware genuinely cannot, and never switch modes afterwards.
• Filesystem — ZFS RAID1 across two disks for anything you care about; ext4 on LVM-thin for a single-disk box.
• Hostname and management IP — both get baked into the node’s identity at install time and are painful to change later.
• Repositories — the default enterprise repo returns HTTP 401 without a subscription key. Swap it for the no-subscription repo before your first apt update.

Everything else you can change from the web UI afterwards.

Proxmox VE is a Debian-based hypervisor that runs KVM virtual machines and LXC containers on bare metal, managed from a web interface on port 8006. The install itself is the easy part. What burns people is not the installer, it is the handful of choices inside it that write themselves into the boot layout, the storage layout, and the node’s identity.

Before you boot the installer

Sort these out in firmware first. Several cannot be applied retroactively without a reinstall.

• Enable hardware virtualization. Intel VT-x or AMD-V. Without it, KVM guests will not start at all. LXC containers still will, which makes the failure confusing.
• Enable IOMMU now if passthrough is anywhere in your plans. Intel VT-d or AMD-Vi. See Proxmox GPU passthrough for what the groups need to look like.
• Pick UEFI and stay there. Proxmox installs a different boot path for UEFI than for legacy BIOS. Flipping the firmware setting after install gives you an unbootable machine that looks like a dead disk.
• Decide the hostname, IP, gateway, and DNS up front. The installer wants an FQDN and a static address.
• Confirm the disks you intend to erase. The installer wipes its targets completely. Physically disconnecting drives you want untouched is cheap insurance.

If the hardware is not settled yet, Proxmox hardware requirements covers what the hypervisor actually needs versus what forum lore insists on.

Writing the ISO and booting it

Download the ISO from the official Proxmox site, verify the published checksum, and write it to a USB stick with a tool that does a raw image write — dd on Linux, Rufus in DD mode on Windows. Avoid tools that “helpfully” repartition the stick: the Proxmox ISO is a hybrid image and expects a byte-for-byte copy.

Boot from the stick and pick the graphical installer. If it fails to come up (some server BMC consoles and old GPUs do not cooperate), the terminal-based installer on the same ISO does the identical job with the same options.

The installer, screen by screen

1. EULA. Accept.
2. Target disk. Select the disk (or disks) Proxmox will own. The Options button behind this screen holds the filesystem choice, which is the most consequential setting in the installer. Details below.
3. Location and time zone. Country, time zone, keyboard layout. Time zone matters more than it looks: consistent clocks are a hard requirement once you build a cluster.
4. Root password and email. That address is where the node sends alerts about failed backups and degraded storage. Use one you actually read.
5. Network. Pick the management NIC, then set the FQDN, the IP with its CIDR prefix, the gateway, and a DNS server.

The network screen deserves a pause. The short hostname becomes the node name, and Proxmox writes the hostname and IP into /etc/hosts and the network config. Renaming a node or moving its management IP later is fiddly and touches the cluster filesystem, storage definitions, and backup jobs. Pick a name that still makes sense when there are four of these.

After the summary, the installer writes to disk and reboots. Pull the USB stick. The console prints the management URL, https://<your-ip>:8006. The certificate is self-signed, so expect a browser warning. Log in as root with realm Linux PAM standard authentication.

The filesystem choice at install time

This is the screen you cannot redo without reinstalling, because it defines the root pool and the boot layout.

ext4 (default). Proxmox creates an LVM layout: a root volume, a swap volume, and a thin pool called local-lvm for guest disks. Simple, well understood, low memory overhead. Thin LVM gives you snapshots for VM disks. It gives you no checksums, no redundancy, and no replication.

xfs. Same LVM structure, different filesystem on root. Choose it if you have a specific reason; otherwise ext4 is the better-trodden path.

ZFS (RAID0, RAID1, RAID10, RAIDZ-1/2/3). The installer builds a bootable ZFS root pool and exposes local-zfs for guest disks. You get checksummed data, cheap snapshots, and Proxmox’s built-in storage replication between nodes. On a mirror, the installer places the bootloader on all pool members, so the box still boots if one disk dies. For any host holding VMs you care about, a two-disk ZFS mirror is the sane default.

btrfs. Offered in the installer but labelled a technology preview. Treat that label as meaning what it says and pick something else for a machine you depend on.

Three practical notes on the ZFS path:

• Never put ZFS on top of a hardware RAID volume. ZFS wants direct access to the physical disks so it can see and repair errors itself. Put the controller in HBA/IT mode, or use a plain HBA.
• The installer’s Options tab exposes ashift, compress, checksum, copies, ARC max size, and hdsize. The defaults are reasonable for modern drives; hdsize is the one to check if you want unallocated space left over.
• ZFS wants RAM, and since Proxmox VE 8.1 the installer caps it for you. New ZFS installs get an ARC maximum of 10% of host memory, clamped to 16 GiB, written to /etc/modprobe.d/zfs.conf; the installer’s ARC max size field is what sets it. That is deliberately conservative next to the upstream ZFS default of roughly half the host’s RAM, so on a large-memory box you may want to raise it rather than lower it. On an older install, or one upgraded in place, check whether any cap is set at all. Read the Proxmox ZFS storage guide before sizing the box.

One warning independent of filesystem: Proxmox writes to its cluster configuration database and logs constantly. Cheap consumer SSDs and USB flash drives wear out quickly under that write pattern. Boot from something with real endurance.

Whatever you choose only constrains the root layout. You can always add storage later: another ZFS pool, NFS, iSCSI, or Ceph.

Post-install: fix the repositories

Fresh installs enable the pve-enterprise repository, which requires a paid subscription key. Without one, apt update fails with a 401 and you cannot install a single update. Recent releases also ship an enterprise Ceph repository that fails the same way.

The fix is to disable the enterprise repos and enable pve-no-subscription. That repo is free, carries the same packages, and is what essentially every homelab runs. It gets less testing than the enterprise repo — fine for a lab, a real consideration for production.

The easy way: in the web UI, go to your node, then Updates → Repositories. Select the enterprise entries and click Disable, then click Add and pick No-Subscription. The GUI writes the correct file, in the correct format, with the correct signing key. If you are not running Ceph, disable the Ceph enterprise repo too.

The CLI way: disable the enterprise entry under /etc/apt/sources.list.d/, then add the no-subscription repo. On releases using one-line entries, that is a file containing:

deb http://download.proxmox.com/debian/pve YOUR-DEBIAN-CODENAME pve-no-subscription

Do not guess the codename — read it off the box with lsb_release -cs or from /etc/os-release, because it changes with each major Proxmox release. Newer Proxmox releases ship deb822-style .sources files instead, which carry an explicit signing-key path. If yours does, use the GUI panel rather than hand-writing that path.

Then update the system:

apt update && apt dist-upgrade

Use dist-upgrade (or apt full-upgrade), not plain upgrade. Proxmox package transitions routinely need to install or remove dependencies, and plain upgrade silently holds those packages back. Reboot if the kernel was updated.

Finally, the subscription nag dialog at login. It appears because you are on the no-subscription repo. The supported way to remove it is to buy a subscription, which also funds the project. Unofficial patch scripts exist, are unsupported, and get overwritten by updates.

First-boot checklist

Work down this list before you create a single VM.

• Confirm virtualization is live. grep -E 'vmx|svm' /proc/cpuinfo should return hits. If it is empty, go back to firmware.
• Check the version. pveversion -v shows the kernel and package set you are actually running.
• Verify the boot setup on ZFS installs. proxmox-boot-tool status confirms every ESP is being kept in sync, which is what makes a mirrored boot disk actually redundant.
• Look at the network. The installer creates a Linux bridge, vmbr0, with your management NIC enslaved to it. Guests attach to that bridge, not the physical NIC. If you need VLANs or extra bridges, do it now: Proxmox network bridges and VLANs.
• Review storage. Under Datacenter → Storage you get local (a directory for ISOs, container templates, and backups) and either local-lvm or local-zfs (block storage for guest disks). Knowing which is which saves confusion when an upload “does not fit”.
• Upload an ISO. Node → local → ISO Images → Upload, or use the download-from-URL option.
• Check disk health. The Disks panel shows S.M.A.R.T. status per device. Confirm the drives are healthy before committing data to them.
• Verify time sync. Fresh installs use chrony; hosts upgraded from older releases may still be on systemd-timesyncd. Confirm whichever one is present is running and the clock is right. Drift is a top cause of weird cluster behaviour later.
• Set up notifications. Point the alert email at a mailbox you read, and send a test. A backup job failing silently for three months is a real failure mode.
• Plan backups before you have anything to lose. Proxmox Backup Server setup is the right target; scheduling and retention are in backup and restore strategy.
• Leave the host alone. Do not install applications on the Proxmox host itself. Put them in a VM or an LXC container — LXC vs VM covers which to pick.
• Consider the firewall. It is off by default at the datacenter level. If this host is near untrusted networks, read Proxmox firewall configuration before exposing it.

Install-time mistakes worth avoiding

• Joining a cluster after building guests. A node must have no VMs or containers on it to join an existing cluster. If a cluster is in your plans, build it first. Proxmox cluster setup has the ordering.
• Reusing disks with stale ZFS labels or old partition tables. Wipe them before the install rather than fighting the installer.
• Single-disk ZFS “for the snapshots”. You get checksums that detect corruption and nothing to repair it with. Useful, but do not mistake it for redundancy.
• Undersizing the boot device. ISOs, container templates, and local backups all land on local. A small boot SSD fills up fast.

Once the node is updated and the checklist is clear, create your first VM. If something misbehaves, common Proxmox problems and fixes is the next stop.