You found a virtual appliance you want to run. Maybe it's a network tool, a NAS distribution, or an old VM someone exported from VMware Workstation years ago. It comes as a single file ending in .ova, and you drag it into the Proxmox web interface expecting an "Import" button to appear. Nothing happens. There isn't one.
That trips up a lot of people moving to Proxmox VE from VMware or VirtualBox, where dragging an OVA into the library just works. Proxmox handles this differently, and once you understand why, the process only takes a few extra minutes.
What You Will Learn
By the end of this tutorial you'll know what's actually inside an OVA file, why Proxmox doesn't import it with one click, and how to get that appliance running as a normal VM anyway. We'll extract the archive, create a VM shell that matches it, pull the virtual disk into Proxmox storage, and fix the handful of boot problems that show up more often than you'd expect.
This is a CLI-heavy guide. You'll spend most of your time in the Proxmox shell rather than clicking through the web interface, and I'll explain every command as we go so nothing feels like a magic incantation.
What Is This Feature?
OVA stands for Open Virtualization Appliance. It's a single file, but it's really just a tar archive wrapping several other files together: an OVF descriptor (an XML file describing the virtual hardware — CPU count, RAM, disk layout, network adapters), one or more virtual disk images (almost always in VMDK format), and a manifest file with checksums to confirm nothing got corrupted in transit.
OVF, without the "A," refers to that same bundle left as loose files in a folder instead of packed into one archive. You'll see appliances distributed either way. Functionally they're the same thing — OVA is just OVF zipped into a single download.
Proxmox VE does have an Import Wizard (under a node, in the storage view), but it's built for a different job: pulling VMs directly off a running VMware ESXi or vCenter host over the network. It reads the live inventory and copies disks across. It was never designed to open a standalone .ova file sitting on your desktop, and as of Proxmox VE 8.x and 9.x, that hasn't changed. For a plain downloaded appliance, the supported path is the command line, using a tool called qm importdisk.
Why Would You Use It?
Honestly, this comes up more than people expect once they start looking around for pre-built appliances. Vendors and open-source projects often ship OVA files because it's the lowest common denominator for "runs on VMware, VirtualBox, and most other hypervisors." Rebuilding one of these from scratch — reinstalling the OS, reapplying vendor configuration — can take hours. Importing the existing disk takes closer to ten minutes.
It's also the fastest way to bring over a VM you exported from an old VMware host before decommissioning it, without setting up a live migration path between the two platforms. If you've only got the exported file and no working ESXi host left to migrate from, this manual import is really your only option.
Prerequisites
Before you start, make sure you have:
- A working Proxmox VE host (8.x or 9.x — the commands here haven't changed between those releases) with shell access, either through the web console or SSH.
- The
.ovaor.ovffile itself, copied onto the Proxmox host or reachable from it. The web GUI's ISO upload only accepts.isofiles, so you'll needscp,sftp, or a mounted network share to get it onto the node. - Enough free space on local storage to hold the extracted files temporarily — figure on roughly double the size of the appliance's disk, since you'll have the compressed original and the extracted copy sitting side by side for a bit.
- Basic familiarity with a Linux shell. Nothing fancy, but you should be comfortable running
cd,ls, andtarwithout hand-holding for every character. - Root access on the Proxmox host, since importing disks and creating VMs both require it.
Step-by-Step Tutorial
We'll use a fictional appliance called router-appliance.ova as the example, sitting in /root/import. Swap in your own filename and path throughout.
1. Copy the file to the node and extract it
From your workstation, copy the OVA over with something like:
scp router-appliance.ova root@192.168.1.50:/root/import/Then, on the Proxmox host itself:
cd /root/import
tar -xvf router-appliance.ovaThat tar -xvf command unpacks the archive in place. x means extract, v prints each filename as it's pulled out (useful so you can see what you're dealing with), and f tells tar which file to read. You should end up with something like router-appliance.ovf, router-appliance-disk1.vmdk, and router-appliance.mf in the same folder. Run ls -lh to confirm the vmdk file is actually there and roughly the size you'd expect — a truncated download will bite you later, not now.
2. Check the OVF file for the specs (optional but worth it)
Open the .ovf file with less router-appliance.ovf or grep it for the numbers you care about:
grep -i "MemorySize\|VirtualQuantity\|ResourceType" router-appliance.ovfThis is just an XML file, and reading it directly isn't fun, but it'll tell you how much RAM and how many vCPUs the vendor originally configured. Manual import doesn't read this automatically the way the ESXi Import Wizard does, so it's on you to match it (or decide you know better).
3. Create an empty VM shell
Now create a new VM with no disk attached yet — just the container for it:
qm create 210 --name router-appliance --memory 2048 --cores 2 --net0 virtio,bridge=vmbr0Pick a VM ID that isn't already in use — 210 here is arbitrary. Adjust --memory and --cores to whatever you found in the OVF, or to what makes sense for your hardware. --net0 virtio,bridge=vmbr0 attaches a VirtIO network adapter to the default bridge. VirtIO is Proxmox's paravirtualized driver set — it's faster than emulating a real NIC or disk controller in software, but it only works if the guest OS has the driver, which most modern Linux distributions do out of the box.
4. Import the virtual disk
This is the actual import step:
qm importdisk 210 router-appliance-disk1.vmdk local-lvmSwap local-lvm for whichever storage you actually want the disk to land on — local-lvm, a ZFS pool, or a Ceph RBD pool all work. This command converts the VMDK and copies it into that storage, then attaches it to VM 210 as an unused disk. It does not pick a bus or controller for you — that's the next step.
If the appliance shipped with more than one disk, run this once per .vmdk file, in the same order they appeared in the original VM.
5. Attach the disk in the Hardware tab
Head to the Proxmox web interface, select VM 210, and open Hardware. You'll see an entry called Unused Disk 0. Double-click it, choose SCSI as the bus (with the VirtIO SCSI controller, set under the VM's Options), and click Add.
Repeat for any additional unused disks, keeping the same order the appliance originally used — most appliances assume disk 0 is the boot disk and get confused if that changes.
6. Fix the boot order
Go to Options → Boot Order and make sure the new SCSI disk is enabled and listed first. A freshly created VM sometimes defaults to booting from an empty CD-ROM drive, which just sits at a blank screen forever and looks like the import failed when it didn't.
7. Boot it and check the console
Start the VM and open the console. Give it a minute — first boot on unfamiliar hardware can take longer than you'd expect while the kernel probes devices. If you see a login prompt or the appliance's own setup screen, you're done. If not, the Troubleshooting section below covers the failures that show up most.
Commands Explained
| Command | What it does |
|---|---|
tar -xvf file.ova | Extracts the OVA archive into its component OVF, VMDK, and manifest files. |
qm create <vmid> --name ... --memory ... --cores ... --net0 ... | Creates a new, empty VM configuration with no disk attached. |
qm importdisk <vmid> <file.vmdk> <storage> | Converts and copies a virtual disk into Proxmox storage, attaching it to the VM as an unused disk. |
qm set <vmid> --scsihw virtio-scsi-pve | Sets the VM's SCSI controller type, useful if you want VirtIO SCSI configured before attaching disks through the GUI. |
qm config <vmid> | Prints the VM's current configuration — handy for confirming what actually got attached and in what order. |
Common Errors
A few things go wrong often enough that they're worth calling out by name.
"unable to open file... No such file or directory" during qm importdisk almost always means a typo in the filename, or you're not in the directory you think you are. Run ls right before the import command and copy the filename exactly — OVA disk names often include spaces or mixed case that don't match what you'd guess.
The VM boots to a black screen with "No bootable device found." Nine times out of ten this is the boot order from step 6 — either the new disk was never enabled in Boot Order, or it's listed after an empty CD drive. Check that first before assuming anything is actually broken.
The appliance boots partway, then hangs or reboots in a loop. Some newer appliances (certain firewall distributions and NAS images in particular) expect UEFI firmware rather than the default SeaBIOS. If the vendor's release notes mention UEFI, set the VM's BIOS option to OVMF (UEFI) under Options, and add an EFI disk when prompted, before you try booting again.
Networking doesn't come up inside the guest, even though the VM shows a link. This is a MAC address problem, not a Proxmox problem. The appliance's OS may have remembered the old network interface name tied to its original MAC address, and now sees a "new" interface it hasn't configured. Inside the guest, check ip a for an interface with a different name than the OS expects, and reconfigure networking to match.
Troubleshooting
If the disk import itself fails partway through with an I/O or format error, double check the file actually finished copying over — run md5sum against the OVA and compare it to whatever hash the vendor published, if they published one. A partial scp transfer is a more common cause of weird import errors than anything wrong with Proxmox.
If the VM boots but the console shows garbled text or nothing at all while the CPU usage graph shows activity, the appliance may be expecting a serial console instead of a VGA display — this is common for network-appliance-style OVAs built for headless operation. Add a serial device under Hardware, set the Display type to Serial terminal under Options, and reboot.
If performance feels sluggish once the appliance is running, check whether the disk actually ended up on VirtIO SCSI or fell back to a slower emulated IDE controller. qm config 210 will show you the current disk bus. Switching an already-running disk to VirtIO SCSI means detaching it, changing the bus type, and reattaching — plan for a short downtime window to do that rather than trying it live.
And if qm importdisk complains about an unrecognized or corrupt VMDK format, open the file with qemu-img info router-appliance-disk1.vmdk first. It'll tell you the actual format and size Proxmox is seeing, which is usually enough to spot whether the file itself is the problem or the command line is.
Best Practices
Give the disk file a short, boring name before you import it — spaces and parentheses in filenames cause more copy-paste mistakes than anything else in this whole process. Rename it once, right after extraction, and save yourself the trouble.
Match RAM and CPU count to whatever the vendor recommends as a minimum, not whatever the OVF happened to specify — some appliances ship configured for a demo environment far smaller than what you actually need in production.
Take a snapshot the moment you get a clean first boot, before you touch any configuration inside the guest. If something goes sideways during setup, rolling back a snapshot is a lot faster than repeating the whole import.
Keep the original OVA file around until you're confident the imported VM is fully working — storage is cheap, and re-running this process from scratch because you deleted the source file is not a good use of an afternoon.
Frequently Asked Questions
Can I import an OVA directly through the Proxmox web interface?
Not a standalone file, no. The built-in Import Wizard only works against a live ESXi or vCenter connection. For a downloaded OVA sitting on disk, the CLI method above is the supported route.
Does this work the same way on Proxmox VE 8 and 9?
Yes. qm importdisk has been stable across both, and nothing in this workflow is version-specific.
What if my OVA contains more than one virtual disk?
Run qm importdisk once per VMDK file, then attach each one under Hardware in the same order the original VM used, so the appliance's boot disk stays first.
Is an OVA the same thing as an ISO?
No. An ISO is a disk image you boot from to install an OS. An OVA is an already-installed, pre-configured virtual machine bundled up to move between hypervisors.
Do I need to install the QEMU Guest Agent after importing?
It's not required to boot, but it's worth adding afterward if the guest OS supports it — it gives Proxmox better visibility into the VM's actual state and makes clean shutdowns more reliable.
Conclusion
The lack of a one-click OVA import button in Proxmox catches a lot of people off guard, especially coming from VMware, but the manual process isn't complicated once you've done it once. Extract the archive, create a matching VM shell, pull the disk in with qm importdisk, and sort out the boot order. Most of the friction in this guide comes from the handful of gotchas — UEFI appliances, stray MAC addresses, forgotten boot order — rather than the import itself.
Once that first appliance is running the way you expect, importing the next one takes a fraction of the time, since you'll already know exactly which screen to check first when something doesn't come up cleanly.