Skip to content

Your First VM

A VM needs two things to be born: an ISO (the install disk of some operating system) and a definition (how much CPU, RAM, and disk it gets). Proxmox separates these cleanly: ISOs live on storage, VMs reference them.

Step 1: upload an ISO

ISOs live on the local storage of your node, which allows the iso content type.

  1. In the resource tree, click your node → local (pve).
  2. Click the ISO Images tab, then Upload.
  3. Choose a Linux ISO — Debian's netinst ISO is a fine first guest. Upload it.

From the docs: the local storage is a directory on the Proxmox host (by default under /var/lib/vz) that holds ISOs, container templates, and backups.

Step 2: create the VM

Click Create VM (top right). The wizard:

  • General: the VM ID (Proxmox suggests the next free number, e.g. 100) and a name like debian-test.
  • OS: choose your uploaded ISO from the dropdown. Set Type to Linux and pick a version close to your ISO.
  • System: defaults are fine (SCSI controller, QEMU guest agent off for now — we'll enable it after install).
  • Disks: one disk, 32 GB is plenty for a first Linux VM. (Disk size can only grow later, never shrink — but 32 GB is small enough not to matter.)
  • CPU: 2 cores to start. You can change this later while the VM is off.
  • Memory: 2048 MB. Ballooning is on by default; leave it.
  • Network: bridged to vmbr0 (the default bridge — Networking explains what that means).
  • Confirm: review, then Finish. Uncheck "start after created" — you'll start it yourself in a moment.

Step 3: install the guest OS

Select the VM → Console → Start. The noVNC console shows the VM booting from your ISO. Install Debian (or your chosen OS) exactly as you would on real hardware. When the installer finishes, the VM reboots — from its virtual disk this time.

From the docs: Proxmox detaches the ISO automatically after install in most flows; if the VM boots back into the installer, check the VM's Hardware tab and remove the CD/DVD drive's ISO.

Step 4: install the guest agent

The QEMU guest agent is a small program inside the guest that talks to Proxmox: clean shutdowns, IP address reporting, and freeze/thaw during snapshots. Install it in the guest:

# Inside the Debian VM (from the docs — the standard Debian package):
apt update && apt install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent

Then tell Proxmox to use it — VM → Options → QEMU Guest Agent → enable it. Or on the host shell (verified against the official qm man page):

qm set 100 --agent 1

Honestly labeled: the qm set form is verified against the official man page (qm set <vmid> [OPTIONS], --agent is a documented option); not executed here.

The qm basics

qm is the command-line VM manager (verified against the official qm(1) man page — every command below exists there). It does everything the UI does:

qm list                  # all VMs on this node: ID, name, status
qm status 100            # is it running?
qm start 100             # power on
qm shutdown 100          # graceful shutdown (needs the guest agent
                         #   or ACPI; otherwise it waits, then stops)
qm stop 100              # hard power-off, like holding the button
qm config 100            # show the VM's full configuration
qm destroy 100           # delete the VM entirely (asks nothing twice)

Honestly labeled: syntax verified against the official man page; not executed in this build environment.

A few habits worth forming early:

  • qm shutdown before qm stop. Guests corrupt filesystems when power-cut, virtual or not.
  • qm config is your friend when something looks wrong — it shows exactly what Proxmox thinks the VM is.
  • VM IDs are yours to choose (100–999999999). Give related machines related numbers: 100s for test boxes, 200s for services.

You have a running VM. Next: when a lighter-weight container would do the same job, in Containers vs VMs.