Proxmox VE Setup Guide

What You Need

• Hardware: a 64-bit x86 machine you can dedicate to Proxmox, with Intel VT-x or AMD-V enabled in the firmware, enough RAM for the guests you plan to run, an SSD for guest storage, and a USB stick for the installer.
• Software: the Proxmox VE 9.x ISO (based on Debian 13 “trixie”). For the ESXi section, admin access to the ESXi host.
• Time: about 1–2 hours for installation and basic setup. VM migrations depend on disk sizes and network speed.

Versions Covered

This guide targets Proxmox VE 9.x. Proxmox VE 9.0 was released on August 5, 2025 and is built on Debian 13 “trixie” (Proxmox release announcement). The previous major release, Proxmox VE 8, is based on Debian 12 and uses different repository lines, so don't mix instructions between the two. If you're still running version 8, follow the official Upgrade from 8 to 9 guide rather than editing repositories by hand.

The newest point release on the Proxmox VE roadmap as of October 9, 2026 is 9.2 (May 21, 2026), on Debian 13.5 with Linux kernel 7.0 as the default. One known issue matters for new installs: the kernel on the 9.2 installer ISO has compatibility problems with RAID controllers that use the megaraid_sas driver and with certain NVMe drives in JBOD mode, fixed in later kernels. On such hardware, the roadmap recommends installing from the 9.1 ISO and then upgrading to 9.2.

What Proxmox VE Includes

• Two kinds of guests: full virtual machines (KVM/QEMU) and Linux containers (LXC), managed side by side.
• A web interface on port 8006 for guests, storage, networking, firewall rules, users and updates. Everything is also scriptable through the CLI (qm, pct, pvesm) and a REST API.
• Backups and snapshots built in, with scheduled backup jobs and retention rules.
• Clustering with live migration of VMs and high availability, without a separate management server.
• Many storage types: ZFS, LVM and LVM-thin, plain directories, NFS and SMB shares, and Ceph.

The software is free and open source under the GNU AGPLv3. Proxmox sells optional subscriptions that add access to the more heavily tested enterprise repository and technical support. Without one, you use the no-subscription repository (set up below).

Hardware Requirements

The official system requirements are modest for the host itself. What you actually need depends on the guests you run, because each VM reserves its own memory and disk.

• CPU: 64-bit x86 (Intel 64 or AMD64) with Intel VT or AMD-V for KVM. Check that virtualization is enabled in the firmware (BIOS/UEFI) settings before installing.
• Memory: Proxmox recommends at least 2 GB for the OS and Proxmox services, plus the memory you assign to guests. ZFS and Ceph need more: roughly 1 GB per TB of used storage. The 1 GB evaluation minimum isn't enough for real use.
• Storage: SSDs give the best results. ZFS and Ceph must not sit behind a hardware RAID controller.
• Passthrough: passing PCIe devices to a VM needs IOMMU support (Intel VT-d or AMD-Vi) in both CPU and motherboard.
• 64-bit ARM: since August 2026, Proxmox VE 9.2 also has an official arm64 build. Full support covers NVIDIA Grace and Vera server platforms; other UEFI-based ARMv9-A hardware is best effort. This guide assumes x86.
• Not supported: Raspberry Pi and other device-tree-only single-board computers. For those, see the Raspberry Pi Setup Guide instead.

Give Proxmox a whole disk. The installer wipes the target disk, and dual-booting a hypervisor causes more trouble than it saves. If you're still deciding what hardware to use, The Complete Self-Hosting Guide for 2026 compares the usual options (an old PC, a mini PC, refurbished servers).

Installation

Download and Write the ISO

Download the Proxmox VE ISO from proxmox.com/downloads and write it to a USB stick. Per the installation media guide, Etcher works as-is. Rufus works too, but you must choose DD mode when it asks (and answer No to its offer to download a different GRUB). On Linux, find the stick with lsblk and write the image with dd:

# Replace /dev/sdX with your USB stick. Double-check: dd overwrites the target without asking.
dd bs=1M conv=fdatasync if=./proxmox-ve_*.iso of=/dev/sdX

Run the Installer

Boot the machine from the USB stick and choose the graphical installer:

1. Accept the license agreement.
2. Select the target disk. Everything on it is erased. Under Options you can pick the filesystem: ext4 or xfs (with LVM-thin for guests), or ZFS if you have the RAM for it and want snapshots and checksums at the storage layer.
3. Set the country, time zone and keyboard layout.
4. Set the root password and an email address for system notifications.
5. Configure the management network: a hostname as a fully qualified name (for example pve.home.arpa), a static IP on your LAN, the gateway (usually your router) and a DNS server. Use an address outside your router's DHCP range, or reserve it in the router, so nothing else gets assigned the same IP.

Reboot when the installer finishes and remove the USB stick.

First Login

Open https://YOUR_IP:8006 in a browser. The certificate is self-signed, so the browser warns you; that's expected on a fresh install. Log in as root with the password you set, realm Linux PAM standard authentication.

Set Up the Package Repositories

A fresh Proxmox VE 9 install has the enterprise repositories enabled: /etc/apt/sources.list.d/pve-enterprise.sources and a preconfigured Ceph enterprise repository in /etc/apt/sources.list.d/ceph.sources. Both need a subscription key, so without one apt update reports errors for enterprise.proxmox.com. Proxmox VE 9 uses the deb822 .sources format; older guides that edit pve-enterprise.list or add a one-line deb entry are written for Proxmox VE 8.

The GUI way: select your node, then Updates → Repositories. Select each enterprise entry and click Disable, then click Add and choose No-Subscription.

The CLI way, following the official Package Repositories page:

# 1. Disable the enterprise repositories: add the line "Enabled: no"
#    to the enterprise stanza in each of these files.
nano /etc/apt/sources.list.d/pve-enterprise.sources
nano /etc/apt/sources.list.d/ceph.sources

# 2. Add the no-subscription repository
cat > /etc/apt/sources.list.d/proxmox.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

# 3. Refresh the package lists and install updates
apt update
apt full-upgrade

After step 1, pve-enterprise.sources should contain the original stanza plus Enabled: no. Leave the Debian base repositories in debian.sources alone; Proxmox needs them as well.

Two details matter here. First, use apt full-upgrade, not apt upgrade: the admin guide explains that Proxmox VE is a rolling release on top of Debian and a plain apt upgrade can leave packages partially upgraded. Second, Proxmox describes the no-subscription repository as suitable for testing and non-production use, because its packages are less heavily tested than the enterprise ones. For a home lab that's the usual choice. If you run Ceph, also add the matching no-subscription Ceph stanza from the same wiki page and keep the Ceph release name your file already uses.

The Subscription Notice

Without a subscription, the web interface shows a “No valid subscription” dialog when you log in. It's informational: clicking OK dismisses it and no features are locked. The supported way to remove it is to buy a subscription.

Many guides patch /usr/share/javascript/proxmox-widget-toolkit/proxmoxlib.js to hide the dialog. Be aware of what that means before you do it: it's unofficial, the code it targets changes between versions, a pattern that doesn't match can break the web interface, and every update of the proxmox-widget-toolkit package overwrites the file, so the dialog comes back. This guide doesn't include such a patch.

VMs vs Containers

Proxmox runs two types of guests. The container documentation describes the trade-offs.

Virtual Machines (KVM)

• Full hardware virtualization with their own kernel
• Run any OS: Windows, Linux, BSD and others
• Strongest isolation from the host
• Each VM reserves its own memory, so overhead is higher

Containers (LXC)

• OS-level virtualization that shares the host kernel
• Linux distributions only
• Some system calls are blocked inside containers for security
• Much lower overhead: faster startup and less RAM than a VM doing the same job

Rule of thumb: use containers for Linux services where low overhead matters. Use VMs for Windows or BSD, for anything that needs its own kernel or kernel modules, and for workloads where you want the strongest isolation.

Creating Your First VM

Upload an ISO

1. In the resource tree, open your node and select the local storage.
2. Open ISO Images.
3. Click Upload to send an ISO from your computer, or Download from URL to have Proxmox fetch it directly.

Create the VM

Click Create VM in the top right. The settings below follow the best-practice notes in the official migration guide, and they're good defaults for new VMs too.

• General: a name and a VM ID (Proxmox suggests the next free ID, starting at 100).
• OS: the ISO you uploaded and the guest OS type.
• System: the default SeaBIOS works for most Linux guests. Windows 11 needs OVMF (UEFI) with an EFI disk and a TPM v2.0 state disk. Tick QEMU Agent if you'll install the guest agent.
• Disks: bus SCSI with the VirtIO SCSI single controller. Enable Discard on SSD or thin-provisioned storage and IO thread.
• CPU: the number of cores. The CPU type matters for live migration: a generic type such as x86-64-v2-AES lets the VM move between hosts with different CPUs, while host passes through every feature of your CPU but ties the VM to similar hardware.
• Memory: the RAM to assign. Leave the ballooning device enabled; even if you don't use ballooning, Proxmox uses it to read detailed memory usage from the guest.
• Network: model VirtIO, bridge vmbr0.

Finish the wizard, start the VM and open Console to install the OS as you normally would. Afterwards, install the guest agent inside Linux guests (apt install qemu-guest-agent on Debian or Ubuntu). Windows guests need the VirtIO drivers, which Proxmox documents on its Windows VirtIO Drivers page.

Creating a Container

Download a Template

1. Select the local storage and open CT Templates.
2. Click Templates.
3. Download a distribution template, for example Debian or Ubuntu.

The same thing from the shell: pveam update, then pveam available to list templates and pveam download local <template-name> to fetch one.

Create the Container

Click Create CT. The wizard is shorter than the VM one because there's no OS installer to run:

• General: hostname, root password and, ideally, your SSH public key. Keep Unprivileged container ticked (the default): root inside the container maps to an unprivileged user on the host.
• Template: the template you downloaded.
• Disks, CPU, Memory: small services need little; you can grow these later.
• Network: bridge vmbr0, with a static IP in CIDR form (for example 192.168.1.50/24) plus gateway, or DHCP.

Start the container. You can open a shell from the host with pct enter <CTID>, use the Console button, or SSH in once networking is up. Before exposing it, apply the same SSH basics you'd use on any server (see Locking Down SSH: Keys, Configs, and Fail2Ban).

Docker: in a VM or in a Container?

Proxmox's own documentation says that for workloads that need maximum isolation and the ability to live-migrate, running application containers inside a QEMU VM remains the recommended practice. For Docker, that means a small Linux VM with Docker installed the normal way (see the Docker Installation Guide).

Running Docker inside an LXC container is possible but comes with caveats from the same docs: the container needs the nesting feature (which exposes host procfs and sysfs contents to the guest), and an unprivileged container also needs keyctl, which the documentation lists as required for Docker. Both are set under the container's Options → Features. If you choose this route, keep it for non-critical services and back up the container before updates.

Storage Configuration

Proxmox treats each storage as a named target with allowed content types (ISO images, container templates, VM disks, backups and so on). The storage documentation lists every type. After a default ext4/xfs install you have two:

local

A directory on the system disk. Used for ISO images, container templates, snippets (cloud-init configs) and, if you allow it, backups.

local-lvm

An LVM-thin pool for VM and container disks. Thin provisioning means a disk only uses the space actually written, and it supports snapshots. A ZFS install creates local-zfs instead.

Adding a Disk

1. Find the new disk with lsblk, or under your node → Disks.
2. If it has old partitions, select it and use Wipe Disk (this destroys its data), then Initialize Disk with GPT.
3. Under Disks, choose LVM-Thin, ZFS or Directory and click Create. Leave Add Storage ticked so it appears as a storage target.

For network storage, use Datacenter → Storage → Add and pick NFS or SMB/CIFS. A common pattern is VM disks on local SSDs and bulk data or backups on a NAS; the TrueNAS Storage Setup guide covers the NAS side. ZFS is worth it if you have several disks and enough RAM: you get redundancy, compression, checksums and snapshots without extra software.

Backups and Snapshots

Snapshots

A snapshot records a guest's state at a point in time on the same storage. It's quick to take and roll back, which makes it ideal before risky changes:

# Take a snapshot of VM 100 (GUI: select the VM → Snapshots → Take Snapshot)
qm snapshot 100 before-changes

# Roll back if the change went wrong
qm rollback 100 before-changes

Snapshots are not backups. They live on the same disk as the guest, so a failed disk takes both with it. Delete old snapshots when you no longer need them, since they keep consuming space.

Backups

A backup is a full, compressed copy you can restore on another storage or another host. See the backup and restore documentation for details.

1. Select a VM or container and open Backup → Backup now.
2. Pick the target storage, the mode (Snapshot backs up a running guest with no downtime; Stop gives the most consistent result) and the compression.

Scheduled Backups

Under Datacenter → Backup → Add, create a job: choose the guests, a schedule, the target storage, the mode and a retention policy (for example keep the last few daily and weekly backups). Store backups on a different physical disk or a NAS, not on the disk the guests run from, and copy important ones off-site as well. Restore one now and then to confirm it works: select the backup in the storage view and click Restore. The backup section of The Complete Self-Hosting Guide for 2026 explains the 3-2-1 approach.

Networking and VLANs

The installer creates a Linux bridge, vmbr0, attached to your physical network card. It works like a virtual switch: every guest attached to it gets an address on your LAN and can reach the internet through your router. For most home labs that's enough to start with.

VLAN-Aware Bridge

To put guests on separate VLANs (for example IoT devices away from your main network), make the bridge VLAN-aware and give each guest's network device a VLAN tag. The network section of the admin guide shows this layout. In /etc/network/interfaces it looks like this (replace eno1 with your NIC name from ip link, and the addresses with yours):

auto lo
iface lo inet loopback

iface eno1 inet manual

auto vmbr0
iface vmbr0 inet static
        address 192.168.1.100/24
        gateway 192.168.1.1
        bridge-ports eno1
        bridge-stp off
        bridge-fd 0
        bridge-vlan-aware yes
        bridge-vids 2-4094

In the GUI, the same setting is the VLAN aware checkbox when you edit vmbr0 under your node → System → Network. Proxmox writes GUI changes to /etc/network/interfaces.new first and applies them when you click Apply Configuration, which helps because a wrong network configuration can make the node unreachable. Then set the VLAN Tag on each guest's network device.

VLANs also need the rest of the network to cooperate: the switch port the Proxmox host is plugged into must carry those VLANs tagged (a trunk port), which requires a managed switch, and your router or firewall needs an interface per VLAN. Networking Fundamentals covers subnets and gateways if those terms are new.

Device Passthrough

USB Passthrough

Useful for things like a Zigbee or Z-Wave stick for a Home Assistant VM:

1. Select the VM and open Hardware → Add → USB Device.
2. Choose Use USB Vendor/Device ID to follow the device wherever it's plugged in, or Use USB Port to pass whatever is in a given port.
3. Restart the VM if the device doesn't appear inside it.

PCIe Passthrough (GPUs, NICs, HBAs)

Passing a whole PCIe device to a VM depends on hardware support, so read the official PCI(e) Passthrough page first. The steps it describes:

1. Enable IOMMU (often labelled VT-d or IOMMU) in the firmware settings.
2. On the kernel side, IOMMU is enabled by default for AMD CPUs, and for Intel CPUs on kernel 6.8 or newer, which includes Proxmox VE 9. Only older kernels need intel_iommu=on on the kernel command line.
3. Load the VFIO modules at boot and rebuild the initramfs:

# /etc/modules-load.d/vfio.conf
vfio
vfio_iommu_type1
vfio_pci

update-initramfs -u -k all
reboot

# After the reboot, check that IOMMU is active
dmesg | grep -e DMAR -e IOMMU -e AMD-Vi

4. Add the device under Hardware → Add → PCI Device.

How cleanly this works depends on the motherboard's IOMMU groups: a device can only be passed through together with everything in its group. Consumer boards vary a lot here, so check your group layout before buying hardware for passthrough.

Migrating from VMware ESXi

The Licensing Background

After Broadcom acquired VMware, it ended the free ESXi hypervisor in early 2024 as part of its move to subscription licensing, which pushed many home labs and small shops to look elsewhere. In April 2025, with ESXi 8.0 Update 3e, Broadcom made a free hypervisor edition available again. According to Broadcom's knowledge base article, the free edition supports up to 2 physical CPUs per host and 8 vCPUs per VM, can't be managed by vCenter, has no vMotion, HA, DRS or VADP-based backups, doesn't support managing hosts through the APIs, and comes without official Broadcom support.

So free ESXi exists again, with those limits. Proxmox VE includes clustering, live migration, HA and a backup scheduler without a license fee, which is why it's a common destination. If you're moving, Proxmox gives you two main paths.

Prepare the Source VMs

The official Migrate to Proxmox VE guide recommends doing these first:

• Uninstall VMware Tools while the VM still runs on ESXi; it's harder to remove afterwards.
• Note each guest's network configuration. The virtual NIC changes, so you'll redo it on the Proxmox side. On Windows, consider removing a static IP configuration first, and update any DHCP reservations for the new MAC address (or set the old MAC on the new NIC).
• Make sure VirtIO drivers are available in the guest (for Linux, in the initramfs) before you move it.
• If a guest uses full-disk encryption with keys in a virtual TPM, have the recovery keys ready: the vTPM state can't be migrated from VMware.
• Power the source VM down before the final import so the disk is consistent.

Option 1: The Built-In Import Wizard

Since Proxmox VE 8.2, the web interface includes an ESXi importer, and it's part of Proxmox VE 9. The steps from the official guide:

1. Make sure Proxmox VE has the latest updates installed.
2. Go to Datacenter → Storage → Add → ESXi. Enter the ESXi host's address and an admin account. If the host uses a self-signed certificate, tick Skip Certificate Verification (or add its CA to the system trust store).
3. Select the new ESXi storage in the resource tree. Its import panel lists the VMs on that host.
4. Select a VM and click Import. Choose the target storage for its disks and the bridge for its network device. The Advanced tab lets you pick per-disk storage, change NIC models or skip devices, and Resulting Config shows exactly what will be created.
5. Power off the source VM, start the import, then boot the new VM and check it.

Limits listed in the guide: disks on VMware vSAN can't be imported, encrypted disks must be decrypted first, datastores with special characters such as + in the name may fail, VMs with snapshots import more slowly, and importing through vCenter instead of directly from the ESXi host is much slower. Run imports one after another rather than in parallel; the guide advises no more than four disks importing at the same time. There's also a live-import option that starts the VM while data is still copying, which shortens downtime, but anything written during the import is lost if it fails, so try it on a test VM first.

Option 2: Manual Disk Import

If the wizard can't reach the host, or you already have the disk files, import them with qm disk import. Proxmox needs access to both the .vmdk descriptor and the -flat.vmdk data file, for example on an NFS share added as storage or copied to the host.

1. Create a new VM with matching settings (firmware, CPU, memory, network) and remove its default disk on the Disks tab.
2. In a shell on the Proxmox host, change to the directory containing the VMDK files and import the disk:

# qm disk import <target VMID> <vmdk file> <target storage>
qm disk import 104 Server.vmdk local-lvm

3. The disk appears in the VM's Hardware panel as an unused disk. Double-click it to attach it. For Windows, use SATA or IDE first; switching to VirtIO SCSI needs extra steps after the drivers are installed.
4. Under Options → Boot Order, enable the disk and put it first.

Older guides use qm importdisk; the current documentation uses qm disk import. If you exported the VM as OVF instead, qm importovf <VMID> <name>.ovf <target storage> creates the VM and its disks in one step.

After the Move

• Firmware: a guest that booted in legacy BIOS mode needs SeaBIOS; one that booted in UEFI mode needs OVMF plus an EFI disk. If a UEFI guest still won't boot, its boot entry may only exist under a custom path; add it in the VM's UEFI setup screen.
• Drivers: once the guest boots, install the QEMU guest agent and switch disks and NICs to VirtIO where the guest supports it.
• Network: reapply the IP configuration you noted earlier.

Troubleshooting

apt update fails for enterprise.proxmox.com

• Likely cause: an enterprise repository is still enabled without a subscription key.
• Check: your node → Updates → Repositories shows the status of each repository, or run grep -r enterprise /etc/apt/sources.list.d/ and see which files still reference it.
• Fix: add Enabled: no to those stanzas (both pve-enterprise.sources and ceph.sources) and run apt update again.

VM won't boot

• Check the boot order under Options → Boot Order, especially after attaching an imported disk.
• Check the firmware: SeaBIOS vs OVMF must match how the OS was installed.
• Check the disk bus: a Windows guest without VirtIO drivers needs SATA or IDE. A Linux guest without VirtIO in its initramfs can often boot its rescue entry, or temporarily use SATA.
• qm config <VMID> prints the VM's full configuration so you can compare it with what you expect.

Container or VM has no network

• Confirm the guest's network device is on the right bridge, with the IP in CIDR form (/24), the right gateway and, if you use VLANs, the right tag. pct config <CTID> shows a container's settings.
• Inside the guest, ip addr and ip route show whether it got the address and default route you expect.
• If the Proxmox firewall is enabled for the datacenter, node or guest, check that its rules allow the traffic.

Web interface unreachable after a network change

• Log in on the physical console (or IPMI) and inspect /etc/network/interfaces. Fix the address, gateway or bridge port, then apply it with ifreload -a.

Host is slow or out of memory

• The node's Summary page and top on the host show which guest is using CPU or RAM.
• Memory is the usual limit: add up what you've assigned to all guests and leave room for the host. If you use ZFS, remember it needs RAM too.
• Use CPU and memory limits on containers that misbehave.

PCIe device can't be passed through

• Check dmesg | grep -e DMAR -e IOMMU -e AMD-Vi for IOMMU messages and lsmod | grep vfio for the three VFIO modules. If either is missing, revisit the passthrough steps above.

Tips

Use Templates

Set up a base VM or container the way you like it (updates, common packages, your SSH key), then right-click it and choose Convert to template. New guests can be cloned from it instead of installed from scratch.

Cloud-Init

For Linux VMs, Cloud-Init sets the hostname, user, SSH keys and network configuration on first boot, so a cloned template comes up ready to use. See Cloud-Init Support.

Clustering and High Availability

Several Proxmox nodes can join a cluster, managed from any node's web interface, with live migration of VMs between them. High availability restarts guests on another node when one fails; it relies on cluster quorum, so read the High Availability documentation before planning for it. A single node is perfectly fine for a home lab.

Performance Basics

• Use VirtIO disk and network devices wherever the guest has drivers.
• Keep VM disks on SSDs. Spinning disks are fine for backups, ISOs and bulk data.
• Enable NUMA for VMs on multi-socket hosts.
• Don't assign more vCPUs to a single VM than the host has cores.