Say you just downloaded a Debian "genericcloud" image, or a coworker handed you a .vmdk file exported from an old VMware box, and you want it running as a VM in Proxmox VE. There's no installer to click through here — the operating system is already sitting inside that file. The normal "create VM, attach ISO, run the installer" flow doesn't apply, and if you go looking for a button labeled "Import Disk" in the GUI, you won't find one.
This is where qm importdisk comes in. It's a command you run from the Proxmox shell that takes an existing disk image — qcow2, vmdk, raw, whatever qemu-img understands — and pulls it into a VM's storage as a disk you can then boot. It's not complicated once you've done it once, but the first time through it's easy to trip over a couple of things: which storage actually accepts which format, and what to do with a VMDK that's really two files instead of one.
I'll walk through both cases below: a qcow2 cloud image and a VMware-exported vmdk, on a fresh Proxmox VE 9.x host.
What You Will Learn
- The difference between an ISO, a disk image, and a "cloud image" — and why you can't just mount one like a CD
- How to build an empty VM shell to hold an imported disk
- The exact syntax for
qm importdisk(akaqm disk importon newer builds) - Why local-lvm and local don't behave the same way when you import a qcow2 file
- How to attach the imported disk, fix the boot order, and actually get the VM to start
- What to do when your vmdk is really two files (a small descriptor plus a large data file)
What Is This Feature?
qm is Proxmox's command-line tool for managing VMs — think of it as the CLI counterpart to the VM section of the web GUI. qm importdisk is one of its subcommands. It takes a disk image file that already exists somewhere on disk and copies (and if needed, converts) it into a storage location where a VM can use it.
A quick rundown of the formats you'll run into:
- qcow2 — QEMU's native copy-on-write format. Supports snapshots, thin provisioning, and compression. Most Linux vendor cloud images and anything built with QEMU natively use this.
- vmdk — VMware's disk format. You'll see this if you're pulling a disk out of ESXi, Workstation, or Fusion. Sometimes it's one file; sometimes it's a small text "descriptor" file plus a separate
-flat.vmdkdata file. - raw — no container format at all, just the bytes of the virtual disk in order. Simple, fast, but no built-in snapshot support at the file level.
A "cloud image" is just a pre-installed OS disk — someone already ran the installer for you and shrank the result down to a small image, usually meant to be customized on first boot via Cloud-Init rather than by hand. Debian, Ubuntu, Rocky, and most other distributions publish these specifically for this kind of import.
Why Would You Use It?
A few real scenarios where this comes up:
- You grabbed a distro's official cloud image instead of an installer ISO, because it boots in about fifteen seconds instead of walking through a text installer.
- Someone exported a VM from VMware as a vmdk and handed it to you directly — no OVA, no OVF, just the raw disk file.
- A vendor ships their appliance as a plain qcow2 (pfSense, some NAS images, various security appliances) rather than as an OVA.
- You're restoring a disk image you pulled off an old server or NAS and want it running again under Proxmox.
Honestly, most of the time people reach for the full OVA/OVF import wizard when they didn't need to. If the vendor already gives you a bare qcow2 or vmdk, skip the OVA wrapper entirely — it's one less layer to fight with, and qm importdisk gets you there faster.
Prerequisites
- A working Proxmox VE 8.x or 9.x host with shell access (SSH or the built-in web shell)
- The disk image file already copied onto the Proxmox host, or reachable over the network with
scp - Enough free space on your target storage — check with
df -hbefore you start, especially if you're converting a large vmdk - At least one storage configured that can hold VM disks (either local, a directory-backed storage, or local-lvm, LVM-thin — both ship by default on a fresh install)
Step-by-Step Tutorial
Step 1: Get the disk image onto your Proxmox host
If you downloaded the image on your laptop, copy it over with scp:
scp debian-13-genericcloud-amd64.qcow2 root@192.168.1.50:/root/Dropping it in /root/ is fine for a one-time import — it's not permanent storage, just a staging spot. qm importdisk copies the data into proper VM storage, so you can delete the original file once you've confirmed the VM boots.
Step 2: Create an empty VM shell
You need a VM to attach the disk to before you can import anything. Easiest way is through the GUI: click Create VM, fill in a name, and on the Disks step, just delete the default disk instead of configuring one. On the OS step you can leave "Do not use any media" selected.
Or do the whole thing from the shell:
qm create 105 --name debian-cloud --memory 2048 --cores 2 \
--net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-single --ostype l26That gives you VM 105, 2 GB of RAM, two cores, a VirtIO network card on the default bridge, and the modern virtio-scsi-single controller for disks. No disk yet — that's next.
Step 3: Run qm importdisk
For the qcow2 cloud image, targeting the local directory storage so it stays as qcow2:
qm importdisk 105 /root/debian-13-genericcloud-amd64.qcow2 local --format qcow2You'll see output like transferred 1.2 GiB of 2.0 GiB (60.00%) scroll by, then a line confirming the disk was added as unused0. On a roughly 2 GB image this takes well under a minute on local SSD storage.
For a VMware export going to LVM-thin storage instead:
qm importdisk 106 /root/web01.vmdk local-lvm --format rawNewer Proxmox VE releases also accept qm disk import as the full command name — importdisk is kept around as an alias, so either one works.
Step 4: Attach the disk in the GUI
Open the VM, go to Hardware, and you'll see a line called Unused Disk 0. Double-click it. A dialog pops up letting you pick the bus type — choose SCSI (it'll ride on the virtio-scsi-single controller you set earlier) and tick Discard if the backing storage is SSD, so TRIM commands pass through and the VM doesn't waste space over time. Click Add.
Step 5: Fix the boot order
This is the step almost everyone forgets. Go to Options → Boot Order, and you'll notice the disk you just added probably isn't checked, or isn't first in line. Enable it and drag it to the top. Skip this and you'll boot straight into the UEFI/BIOS shell with a "No bootable device" message, even though the disk is perfectly fine.
Step 6: Start the VM and check the console
qm start 105Open the console from the GUI (noVNC by default). A properly imported cloud image should boot to a login prompt within a few seconds. If it's a cloud image expecting Cloud-Init — a small service that configures hostname, network, and a default user on first boot — it'll sit waiting for that configuration rather than presenting a normal login. You'd need to attach a Cloud-Init drive and set a user/password on the Cloud-Init tab before it's usable; that's a bigger topic on its own, so if your image needs it, treat this import as step one and the Cloud-Init setup as step two.
Commands Explained
| Command | What it does |
|---|---|
qm create | Creates a new, empty VM definition with the settings you specify |
qm importdisk (alias qm disk import) | Copies/converts an external disk image into a storage location and attaches it to a VM as an unused disk |
--format | Tells the import which format to write when the target storage is file-based (qcow2, raw, or vmdk). Block storage like LVM-thin ignores this and always stores raw |
qm set <vmid> --scsi0 <storage>:<disk> | Attaches an already-imported disk manually, if you'd rather skip the GUI dialog |
qm resize <vmid> scsi0 +10G | Grows the imported disk after the fact — handy since most cloud images ship deliberately small |
qm start / qm stop | Starts or forcibly stops the VM |
Common Errors
A few messages you'll actually run into:
unable to parse directory volume name 'web01.vmdk'Usually means you pointed the command at a path Proxmox doesn't recognize as a plain file — double-check the full path and that the file actually exists at that location (ls -lh /root/web01.vmdk).
qemu-img: Could not open '/root/web01.vmdk': Could not open '/root/web01-flat.vmdk': No such file or directoryThis one trips up almost everyone the first time they import a VMware disk. A vmdk exported from VMware is often two files: a tiny descriptor (web01.vmdk, just a few KB of text pointing at the real data) and the actual data file (web01-flat.vmdk, which can be many gigabytes). You have to copy both files into the same directory and import the descriptor — qemu-img follows the reference automatically. If you only copied the small file, this is the error you'll get.
format ovmf.qcow2 not supported by LVM-thin storage (or similar)LVM-thin storage (local-lvm by default) only stores raw block volumes — it has no concept of a qcow2 file sitting inside it. If you need actual qcow2 files on disk (for portability, or because you want to inspect them with qemu-img later), target a directory storage like local instead. This one catches people constantly, because the GUI doesn't warn you up front — it just quietly converts to raw when you import to LVM-thin, format flag or not.
Troubleshooting
If the VM boots to "No bootable device," go back to Options → Boot Order — nine times out of ten the imported disk either isn't checked or isn't first.
If the disk never showed up as Unused Disk 0 at all, check the import command's output for errors rather than assuming it silently succeeded — a failed qemu-img convert partway through will sometimes still leave a partial, unusable volume behind that you'll need to delete manually from the storage.
If the VM boots but hangs at a black screen or a UEFI shell instead of your OS, check that the machine type and BIOS setting match what the image expects. A disk built for UEFI boot generally needs the VM's BIOS set to OVMF (UEFI) under Options, plus an EFI disk added — a disk imported for a legacy BIOS install won't boot cleanly under OVMF and vice versa.
If it boots but there's no login prompt and no obvious error, and it's a cloud image, that's expected — it's waiting on Cloud-Init to hand it a user and password. That's not a failed import; it just means there's a second setup step ahead of you.
Best Practices
Keep the original image file around until you've confirmed the VM boots and behaves — don't delete your only copy the moment the import finishes.
Use virtio-scsi-single as the controller and SCSI as the bus for imported disks where the guest OS supports it. It's noticeably faster than IDE and, unlike the old default scsi-hw, gives each disk its own queue, which matters if you ever add more than one.
Pick your target storage based on what you actually need. If you want qcow2-level snapshots and easy file-level portability, use a directory storage. If you want the extra performance and simplicity of LVM-thin, accept that it'll always be raw underneath — that's not a downside, just a tradeoff to know about going in.
Resize the disk before you boot it for the first time if you already know you'll need more room — running qm resize after the OS is installed works too, but you'll usually still need to grow the filesystem inside the guest afterward, so it's one less thing to do twice.
Frequently Asked Questions
Can I import a raw .img file the same way?
Yes — qm importdisk handles raw, qcow2, and vmdk the same way, since it's really just calling qemu-img convert underneath. Point it at the .img file and pick your target storage as usual.
Do I need to convert the format myself before importing?
No. The import command converts to whatever the target storage supports automatically. Pre-converting with qemu-img convert is only worth doing if you specifically want a different intermediate file for some other purpose.
Why does my imported disk show up as "Unused Disk 0" instead of already attached?
That's normal — importdisk deliberately leaves the disk unattached so you choose the bus type (SCSI, SATA, IDE, VirtIO Block) rather than guessing for you. Double-click it in Hardware to finish attaching it.
Is this the same thing as the OVA/OVF import wizard?
No. The OVA/OVF wizard unpacks a whole packaged appliance — disks, CPU/RAM settings, network config — in one step. qm importdisk only handles a bare disk file; you build the VM shell yourself. Use the wizard for full appliances, and importdisk when you already have (or only have) a raw disk image.
What if qemu-img says the image is corrupted?
Re-download it and check the vendor's published checksum first — a truncated or partial download is the most common cause, especially for anything transferred over a flaky connection.
Conclusion
Once you've done this once, it's a two-minute job the next time: copy the file over, create a shell VM, run one importdisk command, attach the disk, fix the boot order. The only real traps are the LVM-thin-is-always-raw behavior and the two-file vmdk situation, and now you know both. It's a genuinely useful shortcut any time a vendor hands you a bare disk image instead of a full installer or an OVA — no need to reach for a heavier tool than the job calls for.