Skip to main content

VM setup

Setting up a VM on Unraid is a flexible way to run full operating systems - such as Windows, Linux, or other platforms - alongside your containers and native apps. Whether you want to test new software, run legacy applications, host a desktop environment, or utilize hardware passthrough for gaming or creative work, Unraid's VM Manager makes the process approachable for all skill levels.

New in Unraid 7.0

Unraid 7.x brings significant enhancements to VMs, including:

  • VM clones and snapshots
  • User-created VM templates
  • Inline XML editing/view
  • Advanced GPU sharing and passthrough features

Check out the VM manager features section for more details.

If you haven’t done so already, please review the Overview & system prep instruction to ensure your hardware and shares are ready for virtualization.

Creating your own virtual machines​

With your system prepared and preferences set, you can create a new VM using the WebGUI.

Before you begin
  • Confirm your isos and domains shares are configured and accessible. Learn more about share management here.
  • Upload your operating system installation ISO and, for Windows VMs, the latest VirtIO drivers ISO to the isos share.
  • Decide whether you will use GPU passthrough or VNC for graphics.

To create a basic VM:

  1. Click Add VM from the Virtual Machines page.
  2. Set the Template to Custom, or select a predefined OS template for common distributions.
  3. Enter a Name and, optionally, a Description for your VM.
  4. Toggle Autostart if you want the VM to start automatically with the array.
  5. Select the Operating System type. This will also adjust the VM icon.
  6. Assign CPU cores to the VM. You can assign up to the number of physical cores available on your host.
  7. Specify the Initial Memory (RAM) for the VM. Refer to your guest OS documentation for recommended values.
  8. Choose the OS Install ISO from your isos share.
  9. Configure the Primary vDisk (location, size, and type).
    • The primary vDisk stores the VM’s operating system.
    • Add additional vDisks as needed using the plus sign.
  10. Select a Graphics Card:
    • Choose VNC for remote access or select a physical GPU for passthrough.
    • Assign a USB keyboard/mouse if using a physical GPU.
    • Set a VNC password if desired.
  11. Assign a Sound Card (optional, but required for HDMI audio via GPU).
  12. Assign USB Devices as needed.
    • Devices must be attached before starting the VM (USB hot-plugging is not supported).
    • The Unraid USB flash device is not available for assignment.
  13. Click Create VM. The VM will start automatically unless you uncheck Start VM after creation.

User VM templates​

Unraid 7.1+ introduces user VM templates, making saving and reusing your custom VM configurations easy. User templates streamline VM deployment and ensure consistency across setups.

To create a user template:

  1. Edit the VM you want to template.
  2. Select Create/Modify template and enter a name.
  3. Your template will now be available in the user templates area on the Add VM screen.

To use a user template:

  • On the VMs page, click Add VM and select your template from the User Templates section.

Import/export:

  • Hover over a user template and click the arrow to export it to your server or download it.
  • On another Unraid system, use Import from file or Upload to add the template.

New in Unraid 7.x: VM Manager​

Unraid 7.x introduces a range of powerful enhancements to the VM Manager, streamlining the process of running and managing VMs. These features cater to beginners and advanced users, making deploying, customizing, and optimizing your VMs simpler.

Highlights
  • Save time with VM clones, snapshots, and reusable templates
  • Fine-tune performance and compatibility with advanced passthrough and storage options
  • Enjoy improved visibility and control with usage stats and inline XML editing
Workflow enhancements
  • VM clones & snapshots: Duplicate VMs or quickly save/restore their state for testing or backup.
  • User VM templates: Save your custom VM configurations and deploy new VMs with just a few clicks.
  • Inline XML view/edit: Instantly view or copy the XML generated by the WebGUI; switch to XML mode for advanced edits.
  • Autostart disable: Choose which VMs start automatically with your array.
  • VM usage statistics: Track resource usage per VM directly from the dashboard.
Advanced hardware & storage options
  • PCI multifunction/other: Assign complex PCI devices or groups for advanced passthrough scenarios.
  • QEMU command-line passthrough: Add custom QEMU arguments for expert-level VM tuning.
  • Storage override: Specify the storage location for each VM’s virtual disk.
  • SSD flag & unmap: Optimize vDisk performance for SSDs and enable discard/unmap support.
  • SR-IOV for Intel iGPU: Share integrated Intel graphics across multiple VMs.
  • VM name validation for ZFS: Prevent the use of unsupported characters in VM names for ZFS pools.
Enhanced graphics and GPU sharing
  • VirGL & QXL virtual GPUs: Share Intel/AMD GPUs among multiple Linux VMs or utilize QXL for multi-screen/memory options.
  • CPU pinning optional: Allow Unraid to manage CPU allocation automatically or manually pin cores as needed.
More advanced features
  • View all graphics cards and VM-assigned IP addresses in the VM tab
  • Support for QEMU ppc64 target and qemu:override
  • Hypervclock support for Windows VMs
  • "Migratable" on/off for the emulated CPU
  • Timer/offset configuration options
  • No keymap/nogpu options available for specific use cases
  • Improved VM icon selection and editing
  • Warnings when assigning the primary GPU as passthrough (may require vBIOS)
  • Boot Unraid VMs into GUI mode with the QXL video driver
  • Various fixes for path and icon issues in XML view

VM snapshots​

VM snapshots allow you to save the current state of your VM at a specific point in time. You can revert to that state if something goes wrong or use snapshots to test changes safely. This is particularly useful before installing new software, making configuration changes, or performing system updates.

How VM snapshots work

When you create a snapshot, Unraid generates an "overlay file" that captures all changes made to your VM after that point. You can think of it like this:

  • Original VM disk: This represents your VM's current state (similar to a photograph).
  • Snapshot overlay: This is a separate file that records all changes made after the snapshot (like a list of edits).
  • VM continues running: Your VM uses both the original disk and the overlay file together.

This setup allows you to create multiple snapshots, with each one generating its own overlay file. This means you can easily revert to any previous state.

Example scenario:

  1. You create a snapshot called "Clean Windows Install."
  2. You install some software and make changes.
  3. You create another snapshot called "After Software Install."
  4. You can now revert to either the clean install or the state after the software installation.
  5. You can also use Block Commit or Block Pull to make changes permanent.

To create a snapshot of your VM:

  1. Go to the VMs page in the WebGUI.
  2. Click on the VM name to expand its details.
  3. Look for the Snapshots section and click Create Snapshot.
  4. Enter a descriptive name for your snapshot (for example, "Before Windows Update" or "Clean Install State").
  5. Memory dump option: In current Unraid builds, the "Memory dump" checkbox is not preselected by default. Checking it includes the VM's RAM for a full memory-backed snapshot (captures the live running state, but is larger and slower to create/restore). Leaving it unchecked creates a disk-only, crash-consistent snapshot (smaller and faster, but any unsaved in-memory data will be lost). Choose based on whether you need full live state preservation or just disk recovery.
  6. Click Create to save the snapshot.
Best practices
  • Create snapshots before making significant changes to your VM.
  • Use descriptive names that help you remember what the snapshot contains.
  • Choose Memory dump based on your needs: enable it for full live state preservation, or leave it off for faster disk-only recovery.
  • Keep snapshots for important milestones, but delete old ones to save storage space.

Snapshot storage​

Snapshots use storage space on your system. Each snapshot saves only the differences between the current state and the snapshot state; however, these differences can still accumulate over time.

Here are some points to consider:

  • QCOW2 disks support snapshots and work well with this feature.
  • Storage location: Snapshots are stored with your VM files, so make sure you have enough space on your cache pools or array.

Snapshot storage location:

  • Snapshot metadata is stored in /etc/libvirt/qemu/snapshotdb/VM_name/.
  • Actual snapshot data is stored alongside your VM files on cache pools or array.
Advanced snapshot concepts

For more detailed technical information about how VM snapshots work, including block diagrams and advanced scenarios with multiple snapshots, see the QEMU snapshots documentation.

Common use cases
  • Before system updates: Create a snapshot before installing Windows updates or Linux package updates. If something goes wrong, you can quickly revert to a previous version.
  • Testing software: Install new applications or make configuration changes. If you're not satisfied with the results, revert to your clean VM snapshots from before the changes.
  • Development work: Create snapshots at different stages of your project. This lets you experiment freely and return to known good states.
  • Backup strategy: While not a replacement for proper backups, snapshots provide quick recovery for recent changes.

Using virtual GPUs and GPU sharing​

Unraid now supports advanced GPU sharing via VirGL and QXL for Linux VMs (and some Nvidia GPUs with the Nouveau driver).

  • To use VirGL: set Graphics Card to Virtual and VM console video driver to VirtIO(3D).
  • To use QXL: set Graphics Card to Virtual and VM console video driver to QXL (best).
  • VirGL does not output to a physical monitor and is not compatible with Windows VMs or standard Nvidia plugins.
  • QXL supports multi-screen and configurable video memory.

Advanced options​

Expand this section to view guidance on the more advanced options

Switch to Advanced View on the Add VM page to access additional settings.

Here are the most important advanced options, broken into focused sections:

CPU mode:

  • Host passthrough: Exposes all host CPU features to the VM for maximum performance.
  • Emulated: Uses a generic CPU model, reducing compatibility issues but limiting performance.

Memory ballooning:

Machine type:

  • i440fx: Default for Windows VMs. Change only if you have GPU passthrough issues.
  • Q35: Default for Linux VMs and recommended for most modern operating systems, especially with GPU passthrough.

BIOS type:

  • SeaBIOS: Traditional BIOS for legacy OSes.
  • OVMF: UEFI BIOS required for Windows 8+, most modern Linux distros, and GPU passthrough.
note

BIOS type can only be set when creating a new VM.

Hyper-V extensions:

  • For Windows VMs, enable Hyper-V extensions for improved compatibility and performance.

VirtIO drivers ISO:

  • Override the default VirtIO ISO if needed, especially for testing or using newer drivers.

vDisk type:

  • RAW: Best performance, less flexible for snapshots.
  • QCOW2: Supports snapshots but offers slightly lower performance.

VirtFS mappings (Linux VMs):

  • Add multiple VirtFS (9p) shares for file system integration between host and guest.
  • See QEMU 9p documentation for details.

Network settings:

  • Modify the Network MAC address or select an alternate Network Bridge.
  • Click the refresh symbol to auto-generate a new MAC address.
  • Add additional virtual network interfaces as needed.
Troubleshooting tips
  • If your VM fails to start, double-check your ISO and vDisk paths.
  • For GPU passthrough, ensure your hardware and BIOS settings support IOMMU/VT-d/AMD-Vi.
  • Some USB devices may not work reliably with passthrough - test and consult the Unraid forums for device-specific advice.

Binding PCI devices for passthrough​

Before you can assign a GPU or any PCI device to a VM, it's important to "bind" the device to the vfio-pci driver. This process hides the device from Unraid and dedicates it solely to your VM.

To bind a PCI device (GPU, USB controller, NVMe, etc.) for passthrough:

  1. Navigate to Tools → System Devices in the WebGUI.
  2. Look through the list of all detected PCI devices and their IOMMU groups.
  3. Check the box next to each device you wish to bind to vfio-pci (to hide it from Unraid).
    • Note that devices already in use by Unraid (such as disk controllers and network cards) cannot be selected.
    • If you select a GPU, select the associated sound device.
  4. Click on Bind Selected to VFIO at Boot to save your changes.
  5. Restart your server for the binding to take effect.
caution

If you make hardware changes (like adding or removing PCI devices), return to System Devices to ensure the correct devices are still bound. If devices are unbound or misbound, they may not appear for passthrough.

After binding, bound devices will appear in the Other PCI Devices dropdown when editing or creating a VM.

Troubleshooting
  • If you've previously used the VFIO-PCI Config plugin, uninstall it - this functionality is now integrated.
  • To reset all bindings, delete /boot/config/vfio-pci.cfg and reboot your system.
  • After rebooting, utilize the View VFIO-PCI Log button on the System Devices page for advanced troubleshooting.
  • Remember that if you bind your only GPU, Unraid may not boot to the GUI. Make sure you plan for this.
  • For more information, check the official guide on the Unraid forums.

GPU passthrough for virtual machines​

GPU passthrough allows you to assign a physical graphics card directly to a VM, providing near-native performance for gaming, creative work, or machine learning.

Why use GPU passthrough?
  • Performance: Direct hardware access for demanding applications.
  • Compatibility: Run graphics-intensive workloads that require a dedicated GPU.
  • Flexibility: Transform your Unraid server into a multi-purpose workstation.

Prerequisites

Hardware:

  • CPU with Intel VT-d or AMD-Vi support (IOMMU enabled in BIOS).
  • GPU compatible with passthrough (see community-tested hardware).
  • A motherboard that properly isolates PCIe devices.

Software:

  • Unraid 6.9+ with virtualization enabled.
  • OVMF (UEFI) bios for VMs (recommended over SeaBIOS).

To set up GPU passthrough:

  1. Ensure your hardware supports IOMMU and is enabled in your BIOS.
  2. Enable virtualization features in BIOS (Intel VT-x/VT-d or AMD-v/AMD-vi).
  3. Update Unraid to the latest stable version.
  4. Assign the GPU to the VM in the VM creation or edit screen under the graphics card section.
  5. Assign a USB keyboard and mouse to the VM if using GPU passthrough.
  6. Use OVMF BIOS for the VM for better compatibility with GPU passthrough.
  7. Start the VM and verify the GPU is passed through correctly.
note

Some GPUs may require additional configuration or ROM injection for proper passthrough.

Manual ROM injection​

Some GPUs, especially specific NVIDIA models, require a ROM file to be manually provided to the VM to initialize correctly. This is often necessary when the GPU’s onboard firmware is not correctly passed through by default, causing issues like black screens or failure to boot. Manual ROM injection is a last resort after trying BIOS and VM configuration adjustments.

To inject a ROM:

  1. Download GPU ROM:

    • Visit TechPowerUp VGA BIOS database.
    • Search for your GPU model and download the correct ROM file.
    • Store the rom in your unraid isos or domains share.

  2. Edit VM XML:

    • Stop the VM and open its XML configuration (Edit XML from the VM context menu).

    • Locate the GPU’s <hostdev> block and add the <rom> tag:


      <hostdev mode='subsystem' type='pci' managed='yes'>
        <driver name='vfio'/>
        <source>
          <address domain='0x0000' bus='0x02' slot='0x00' function='0x0'/>
        </source>
        <rom file='/mnt/user/isos/gpu_roms/your_gpu.rom'/> <!-- Update path -->
        <address type='pci' domain='0x0000' bus='0x00' slot='0x05' function='0x0'/>
      </hostdev>

  3. Save and test: Click Update and start the VM.

Common issues​

This section covers advanced topics and solutions for common issues when managing VMs on Unraid. Expand the sections below for step-by-step instructions and troubleshooting tips.

Expand a vDisk​

Click to expand/collapse

If your VM is running low on disk space, you can increase the size of its vDisk directly from the WebGUI.

To expand a vDisk:

  1. Go to the VMs tab in the WebGUI.
  2. Ensure the VM is stopped.
  3. Click on the VM’s name to expand its details.
  4. Locate the vDisk you want to expand. Click the value in the Capacity field to make it editable.
  5. Enter the new desired size (e.g., 100G for 100 gigabytes) and press Enter.
  6. The new capacity is now set.
note

You cannot shrink a vDisk from the Unraid GUI; only expansion is supported.

Expanding the partition in your guest OS

After resizing the vDisk, start your VM. You must expand the partition within the guest operating system to use the new space:

  • Windows: Use the built-in Disk Management tool to extend your partition.

  • Linux (LVM): Use tools like fdisk, pvresize, lvextend, and resize2fs to expand partitions and logical volumes.

    Example:

    sudo fdisk /dev/vda
    sudo pvresize /dev/vda3
    sudo lvextend -l +100%FREE /dev/mapper/ubuntu--vg-ubuntu--lv
    sudo resize2fs /dev/mapper/ubuntu--vg-ubuntu--lv

    Adjust device names as needed for your setup.

tip

Always back up your VM before making disk changes.

Stuck at UEFI shell​

Click to expand/collapse

If your VM boots to a UEFI shell instead of your operating system, you can manually start the boot process:

At the UEFI shell prompt, enter:

fs0:
cd efi/boot
bootx64.efi

The VM should now continue booting into your OS.

tip

If this happens frequently, check your VM’s boot order and ensure the correct vDisk or ISO is set as the primary boot device in the VM settings.

Black screen after VM start​

Click to expand/collapse

If your VM starts but the display remains blank:

  1. Check BIOS settings:

    • Set primary graphics to integrated GPU (iGPU), not the passthrough GPU.
    • Update motherboard and GPU BIOS to the latest versions.

  2. Adjust VM settings:

    • Switch from SeaBIOS to OVMF (UEFI) in VM settings.
    • Change Machine Type from i440fx to Q35.

  3. Manual ROM injection (last resort): Inject GPU ROM manually.

Error: "Failed to set IOMMU for container: operation not permitted"​

Click to expand/collapse

This error typically indicates IOMMU group conflicts or missing interrupt remapping:

  1. Enable PCIe ACS override:

    • Go to Settings → VM Manager.
    • Set PCIe ACS override to Downstream or Both.
    • Reboot Unraid.

  2. Allow unsafe interrupts (advanced):

    • Edit syslinux.cfg on your unraid flash drive:

      append vfio_iommu_type1.allow_unsafe_interrupts=1 initrd=/bzroot

    • Only use this if you fully trust your VM guests.

note

For detailed IOMMU group explanations, we recommend checking out Alex Williamson’s blog.