This content follows experimental nightly development software. Pre-release software is intended for testing purposes only. Use the Product and Version selectors above to view content specific to a stable software release.
TrueNAS 25.04 changes the virtualization hypervisor backend from the previous KVM implementation (TrueNAS 24.10 and earlier) to Incus for virtual machine (VM) deployment and adds support for linux system containers (LXC), with lightweight isolation functionality similar to jails in TrueNAS CORE.
This is an experimental community feature, with full Enterprise support planned for a future TrueNAS release version.
With this change comes redesigned Virtualization screens in the TrueNAS UI.
The content in this article is in the process of being rewritten to reflect new virtualization features and procedures.
Migrating VMs from 24.10 to 25.04
Manual Migration Required
Due to configuration incompatibilities between the previous KVM hypervisor implementation (TrueNAS 24.10 and earlier) and Incus in TrueNAS 25.04 (and later), existing VMs do not automatically migrate on upgrade from 24.10.X to 25.04.
However, storage zvols are retained, allowing users to easily recreate previously configured VMs.
Manual Migration Instructions
To manually migrate VMs from 24.10 (latest) to 25.04, users should first prepare to migrate by gathering image files and recording existing configuration settings.
After updating to 25.04, use the configuration details gathered above to recreate VMs with the same resource allocations and mount existing storage zvols.
Preparing to Migrate VMs from 24.10
Screenshot or record existing VM configuration(s).
Go to Virtualization and click on a VM to expand that row.
Click Edit to open the Edit VM screen and note the existing configuration.
Save your configuration settings in an external location to reference later.
These settings do not migrate and must be recreated after upgrading to 25.04.
Record the existing zvol storage location and virtual device configuration.
Go to Virtualization and click on a VM to expand that row.
Click device_hubDevices.
Click more_vert in the Disk row and select Edit.
Note the configured path in Zvol as well as the storage Mode and the Disk Sector Size.
Continue to note all other VM devices and associated configuration settings.
Record this information in an external location along with the configuration settings gathered above.
Locate or download the required iso image files.
Access the VM via Display or Serial Shell and confirm the installed OS and version.
Refer to documentation for the installed OS if needed to locate the installed version.
If the installed image (iso) file is stored on the TrueNAS system or in an external location, note this path and record it along with the other configuration settings.
If needed, download a fresh image file matching the installed OS and Version
Recreating VMs in 25.04
After upgrading to 25.04, go to Virtualization and click Select Pool to open the virtualization Global Settings screen.
Use the Pool dropdown to select a pool for virtualization service storage.
Accept default networking settings or modify as needed, then click Save.
Click Create New Instance and recreate previous VM configuration(s).
Select VM for Virtualization Method and select or upload the iso file in Image.
Using the configuration settings you recorded before updating, replicate the previous VM configuration.
Select the existing zvol for the VM as the storage source in Disks.
Click Create.
The Virtual Machines screen allows users to add, edit, or manage virtual machines (VMs) and VM devices.
The No Virtual Machines screen displays if there are no VMs configured on the system or if you delete all VMs on the system.
Add Virtual Machines and Add at the top right of the screen opens the Create Virtual Machine wizard.
The screen displays a list of VMs configured on the TrueNAS system.
The State toggle displays and changes the state of the VM.
Autostart, when selected, automatically starts the VM if the system restarts, otherwise manually start the VM.
Click on a VM to expand it and open the details screen with details on that VM and options for a VM.
Click Start to start the VM and show additional options.
Create Virtual Machine Wizard Screens
The Create Virtual Machine configuration wizard displays all settings to set up a new virtual machine.
Use Next and Back to advance to the next or return to the previous screen to change a setting.
Use Save to close the wizard screens and add the new VM to the Virtual Machines screen.
Operating System Screen
The Operating System settings specify the VM operating system type, the time the VM system clock uses, the boot method, and display type.
Required. Select the VM operating system type from the dropdown list. Options are Windows which adds the Enable Hyper-V Enlightenments option. Linux, and FreeBSD.
Enable Hyper-V Enlightenments
Only displays when Guest Operating System is set to Windows. This emulates a Hyper-V-compatible hypervisor for the Windows guest operating system and makes some Hyper-V-specific features available.
Name
Required. Enter an alphanumeric name for the virtual machine.
Description
(Optional) Enter a description of your choosing. For example, the type of OS for the VM or the VM use.
System Clock
Select the method to use to set the system the VM from the dropdown list. Options are Local which uses the TrueNAS system clock setting, or UTC to use the Coordinated Universal Time clock. The default is Local.
Boot Method
Select the boot method option from the dropdown list. Options are UEFI for newer operating systems or Legacy BIOS for older operating systems that only support BIOS booting.
Shutdown Timeout
Enter the time in seconds the system waits for the VM to cleanly shut down. During system shutdown, the system initiates power-off for the VM after the shutdown timeout entered expires.
Start on Boot
Select to start the VM when the system boots. Selected by default.
Enable Display
Enables a display (Virtual Network Computing) remote connection. Requires UEFI booting. Selected by default.
Bind
Displays when Enable Display is selected. Select an IP address to use for remote VNC sessions. Note that this setting only applies if you are using a VNC client other than the TrueNAS WebUI.
Password
Displays when Enable Display is selected. Enter a password for the VNC display to use to securely access the VM.
CPU and Memory Screen
The CPU and Memory settings specify the CPU mode, model, and memory size. They also let you specify the number of virtual CPUs to allocate to the virtual machine, the number of cores per virtual CPU socket, and the number of threads per core.
(Required) Enter the number of virtual CPUs to allocate to the virtual machine. The maximum is 16, or fewer if the host CPU limits the maximum. The VM operating system might impose operational or licensing restrictions on the number of CPUs. Default setting changes with the option selected in Guest OS, for Windows it is 2, for Unix-type it is 1.
Cores
(Required) Enter the number of cores per virtual CPU socket. The product of vCPUs, cores, and threads must not exceed 16.
Threads
(Required) Enter the number of threads per core. A single CPU core can have up to two threads per core. A dual-core could have up to four threads. The product of vCPUs, cores, and threads must not exceed 16.
Optional: CPU Set (Examples: 0-3,8-11)
Specify the logical cores that the VM can use. Better cache locality can be achieved by setting the CPU set based on CPU topology. E.g. to assign cores: 0,1,2,5,9,10,11 you can write: 1-2,5,9-11
Pin vcpus
When the number of vCPUs equals the number of CPUs in CPU Set, vCPUs can be automatically pinned into CPU Set. Pinning is done by mapping each vCPU into a single CPU number following the order in CPU Set. This improves CPU cache locality and can reduce possible stutter in GPU passthrough VMs.
CPU Mode
Select the CPU mode attribute from the dropdown list to allow your guest VM CPU to be as close to the host CPU as possible. Select Custom to make it so a persistent guest virtual machine sees the same hardware no matter what physical machine the guest VM boots on. It is the default if the CPU mode attribute is not specified. This mode describes the CPU presented to the guest. Select Host Model to use this shortcut to copy the physical host machine CPU definition from the capabilities XML into the domain XML. As the CPU definition copies just before starting a domain, a different physical host machine can use the same XML while still providing the best guest VM CPU each physical host machine supports. Select Host Passthrough when the CPU visible to the guest VM is the same as the physical host machine CPU, including elements that cause errors within libvirt. The downside of this is you cannot reproduce the guest VM environment on different hardware.
CPU Model
Select a CPU model to emulate.
Memory Size
Allocate RAM for the VM. The minimum value is 256 MiB. This field accepts human-readable input (Ex. 50 GiB, 500M, 2 TB). If units are not specified, the value defaults to bytes.
Minimum Memory Size
(Optional) When not specified, the guest system is given a fixed amount of memory specified in Memory Size. When minimum memory is specified, the guest system is given memory within a range between minimum and fixed as needed. Enter a value smaller than the Memory Size to enable a variable RAM amount as needed within a range between this value and the one entered in Memory Size.
Optional: NUMA nodeset (Example: 0-1)
Node set allows setting NUMA nodes for multi NUMA processors when CPU set was defined. To achieve better memory locality, setting nodeset based on assigned cpuset. For example, if CPUs 0,1 belong to NUMA node 0, then setting nodeset to 0 improves memory locality.
Disks Screen
The Disks settings allow specifying how virtual disks are added. Options are to create a new zvol on an existing dataset for a disk image or use an existing zvol or file for the VM. You also specify the disk type, zvol location, and size.
Select to create a new zvol on an existing dataset to use as a virtual hard drive for the VM.
Use existing disk image
Select to use an existing zvol or file for the VM. Displays the Select Disk Type and Select Existing Zvol dropdown list fields.
Select Disk Type
Displays after selecting Use existing disk image. Select the desired disk type. Options are AHCI or VirtIO. Select AHCI for Windows VMs. VirtIO requires a guest OS that supports VirtIO paravirtualized network drivers.
Select Existing Zvol
(Required) Displays after selecting Use existing disk image. Select an existing zvol from the dropdown list.
Zvol Location
(Required) Displays after selecting Use existing disk image. Select a dataset for the new zvol from the dropdown list of datasets on the system.
Size
(Required) Displays after selecting Use existing disk image. Allocate space for the new zvol. (Examples: 500 KiB, 500M, 2 TB). Units smaller than MiB are not allowed.
Network Interface Screen
The Network Interface settings specify the network adapter type, mac address, and physical network interface card associated with the VM.
Select the adapter type from the dropdown list. Options are:
Intel e82545 (e1000) emulates the same Intel Ethernet card and provides compatibility with most operating systems.
VirtIO provides better performance when the operating system installed in the VM supports VirtIO para-virtualized network drivers.
Mac Address
Enter the desired address into the field to override the randomized MAC address.
Attach NIC
Select the physical interface to associate with the VM from the dropdown list.
Trust Guest Filters
Select to enable and allow the virtual server to change its MAC address. As a consequence, the virtual server can join multicast groups. The ability to join multicast groups is a prerequisite for the IPv6 Neighbor Discovery Protocol (NDP). Setting Trust Guest Filters to yes has security risks because it allows the virtual server to change its MAC address and so receive all frames delivered to this address. Disabled by default.
Installation Media Screen
The Installation Media settings specify the operation system installation media image on a dataset or upload one from the local machine.
Enter the path or browse to the location where you want to install the image file.
Choose File
Click to save the path populated in the ISO save location field.
Upload
Click to upload the file selected in the ISO save location field.
GPU Screen
The GPU settings specify the graphic processing unit (GPU) for the VM. It also provides the option to hide the VM from the Microsoft Reserved Partition (MSR) on Windows systems.
Select to enable the VM to hide the GPU from the Microsoft Reserved Partition (MSR).
Ensure Display Device
Select to ensure that the guest always has access to a video device. Required for headless installations like Ubuntu server for the guest to operate properly. Leave the checkbox clear for cases where you want to use a graphic processing unit (GPU) passthrough without adding a display device.
GPUs
Select a physical GPU on your system from the dropdown list to use for the VM.
Confirm Options Screen
The Confirm Options screen displays a summary of settings for the VM. It shows the number of CPUs, cores, threads, memory, name of the VM, and the disk size.
Click Save to add the VM to the Virtual Machines screen. Click Back to return to the previous screens to make changes.
Virtual Machine Details Screen
Expand any VM on the Virtual Machines screen to show the details and options for a VM.
Details include the basic information on the number of virtual CPUs, cores, and threads, the amount of memory, boot load and system clock types, the display port number, and the shutdown timeout in seconds.
Starting the VM shows additional options for the VM.
VM Options
Operation
Icon
Description
Start
Starts a VM. The toggle turns blue when the VM switches to running. Toggles to Stop. Clicking Start shows the Restart,Power Off, Display, and Serial Shell buttons.
Restart
replay
Restarts the VM.
Power Off
power_settings_new
Powers off and halts the VM, similar to turning off a computer power switch.
Stop
stop
Stops a running VM. Because a virtual machine does not always respond well to STOP or the command might time out if the VM does not have an OS. Use Power Off instead.
Edit
mode_edit
Opens the Edit Virtual Machine that displays editable VM settings. You cannot edit a VM while it is running. Stop the VM and then you can edit the properties and settings.
Delete
delete
Deletes a VM. Opens a delete dialog that allows you to remove the VM from your system. You cannot delete a virtual machine that is running. You must first stop the VM and then you can delete it.
Devices
device_hub
Opens the Virtual Machine Devices screen for the selected VM. Shows a list of configured devices for the VM. By default, all VMs show the Disks, NIC, and Display devices.
Clone
Makes an exact copy or clone of the VM. Opens the Clone dialog that allows you to clone the selected VM. Enter a name for the cloned VM. Naming the clone VM is optional. The cloned VM displays on the Virtual Machines list with the extension _clone0. If you clone the same VM again the extension for the second clone is clone1.
Display
settings_ethernet
Opens the SPICE login screen in a browser window and allows you to connect to the remote desktop.
Serial Shell
keyboard_arrow_right
Opens the TrueNAS VM Serial Shell screen.
Download Logs
content_paste
Downloads a .log file to the system.
Delete Virtual Machine Dialog
Delete removes the VM configuration from your system.
Select to remove the data associated with this virtual machine. Deleting a VM results in data loss if the data is not backed up. Leave unselected to keep the VM data intact.
Force Delete
Select to ignore the virtual machine status during the delete operation. Leave unselected to prevent deleting the VM when it is still active or has an undefined state.
Enter vmname below to confirm
Enter the name of the VM to confirm you want to delete the selected VM.
Clone Virtual Machine Window
The Clone dialog allows you to create an exact duplicate of the VM using the name entered.
Naming the clone VM is optional. The cloned VM displays on the Virtual Machines list with the extension _clone0.
If you clone the same VM again the extension for the second clone is clone1.
VM Serial Shell Screen
Click Serial Shell to open the VM Serial Shell screen where you can enter commands for the selected virtual machine.
Click Virtual Machines in the header to return to the Virtual Machine screen.
Edit Virtual Machine Screen
The Edit VM screen settings are a subset of those found on the Create Virtual Machine screens.
It only includes the general settings found on the wizard Operating System screen, CPU and Memory, and GPUs screen settings.
To edit disks, network, or display settings, click Devices on the expanded view of the VM to open the Devices screen.
Edit General Settings
The Edit screen General Settings specify the basic settings for the VM. Unlike the Create Virtual Machine wizard, you cannot change the Enable or Start on Boot status or change the display type or bind address for a saved VM from this screen.
Required. Enter an alphanumeric name for the virtual machine.
Description
Enter a description (optional).
System Clock
Select the VM system time from the dropdown list. Options are Local or UTC. The default is Local.
Boot Method
Select the boot method option from the dropdown list. Select UEFI for newer operating systems or Legacy BIOS for older operating systems that only support BIOS booting.
Shutdown Timeout
Enter the time in seconds the system waits for the VM to cleanly shut down. During system shutdown, the system initiates power-off for the VM after the shutdown timeout entered expires.
Start on Boot
Select to start this VM when the system boots.
Enable Hyper-V Enlightenments
Shows for VMs set for Windows OS. KVM implements Hyper-V Enlightenments for Windows guests. These features make Windows think they are running on top of a Hyper-V-compatible hypervisor and use Hyper-V-specific features. In some cases enabling these enlightenments might improve the usability and performance on the guest.
To edit display type or bind address after VM creation (click to expand)
Go to Virtualization > Virtual Machines and locate the VM you want to modify.
Click anywhere on the VM entry on the Virtual Machines widget to expand it.
Click device_hubDevices to open the devices screen associated with the VM.
From this screen, click the more_vert icon at the right of the display device and select Edit to open the Edit Display Device screen.
Use the Bind dropdown to select a new IP address.
Edit CPU and Memory Settings
The CPU and Memory settings on the Edit VM screen are the same as those in the Create Virtual Machine wizard.
(Required) Enter the number of virtual CPUs to allocate to the virtual machine. The maximum is 16, or fewer if the host CPU limits the maximum. The VM operating system might impose operational or licensing restrictions on the number of CPUs. Default setting changes with the option selected in Guest OS, for Windows it is 2, for Unix-type it is 1.
Cores
(Required) Enter the number of cores per virtual CPU socket. The product of vCPUs, cores, and threads must not exceed 16.
Threads
(Required) Enter the number of threads per core. A single CPU core can have up to two threads per core. A dual-core could have up to four threads. The product of vCPUs, cores, and threads must not exceed 16.
Optional: CPU Set (Examples: 0-3,8-11)
Specify the logical cores that the VM can use. Better cache locality can be achieved by setting the CPU set based on CPU topology. E.g. to assign cores: 0,1,2,5,9,10,11 you can write: 1-2,5,9-11
Pin vcpus
When the number of vCPUs equals the number of CPUs in CPU Set, vCPUs can be automatically pinned into CPU Set. Pinning is done by mapping each vCPU into a single CPU number following the order in CPU Set. This improves CPU cache locality and can reduce possible stutter in GPU passthrough VMs.
CPU Mode
Select the CPU mode attribute from the dropdown list to allow your guest VM CPU to be as close to the host CPU as possible. Select Custom to make it so a persistent guest virtual machine sees the same hardware no matter what physical machine the guest VM boots on. It is the default if the CPU mode attribute is not specified. This mode describes the CPU presented to the guest. Select Host Model to use this shortcut to copy the physical host machine CPU definition from the capabilities XML into the domain XML. As the CPU definition copies just before starting a domain, a different physical host machine can use the same XML while still providing the best guest VM CPU each physical host machine supports. Select Host Passthrough when the CPU visible to the guest VM is the same as the physical host machine CPU, including elements that cause errors within libvirt. The downside of this is you cannot reproduce the guest VM environment on different hardware.
CPU Model
Select a CPU model to emulate.
Memory Size
Allocate RAM for the VM. The minimum value is 256 MiB. This field accepts human-readable input (Ex. 50 GiB, 500M, 2 TB). If units are not specified, the value defaults to bytes.
Minimum Memory Size
(Optional) When not specified, the guest system is given a fixed amount of memory specified in Memory Size. When minimum memory is specified, the guest system is given memory within a range between minimum and fixed as needed. Enter a value smaller than the Memory Size to enable a variable RAM amount as needed within a range between this value and the one entered in Memory Size.
Optional: NUMA nodeset (Example: 0-1)
Node set allows setting NUMA nodes for multi NUMA processors when CPU set was defined. To achieve better memory locality, setting nodeset based on assigned cpuset. For example, if CPUs 0,1 belong to NUMA node 0, then setting nodeset to 0 improves memory locality.
Edit GPU Settings
The GPU settings on the Edit screen are the same as those in the Create Virtual Machine wizard.
Select to enable the VM to hide the GPU from the Microsoft Reserved Partition (MSR).
Ensure Display Device
Select to ensure that the guest always has access to a video device. Required for headless installations like Ubuntu server for the guest to operate properly. Leave the checkbox clear for cases where you want to use a graphic processing unit (GPU) passthrough without adding a display device.
GPUs
Select a physical GPU on your system from the dropdown list to use for the VM.
Devices Screens
The Devices screen displays a list of VM devices configured on your system.
By default, every VM displays three devices: Disks, NIC, and Display.
Add opens the Add Device screen. Settings change based on the various device types.
Device Actions
Each device listed on the Devices screen has the same three options, accessed by clicking the more_vert at the right of the device row:
Edit opens the Edit type Device screen where type is the device type selected.
Settings vary based on the type of device selected in Device Type. See Add Device screen.
Device Type only displays on the Add Device screens.
Delete opens a dialog. Delete Device confirms you want to delete the device.
Details opens an information dialog that lists the port, type, bind IP, and other details about the device.
Click Close to close the dialog.
Devices Add Screens
The Add Device screen displays different settings based on the Device Type selected.
Add CD-ROM Device Type Settings
Select CD-ROM in Device Type to see the CD-ROM settings.
Select the device type from the dropdown list. CD-ROM is the default setting.
CD-ROM Path
Use the to the left of /mnt to browse to the location of the CD-ROM file on the system.
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.
Add NIC Device Type Settings
Select NIC in Device Type to see the VM network interface card settings.
Required. Select the emulator type from the dropdown list. Emulating an Intel e82545 (e1000) Ethernet card provides compatibility with most operating systems. Change to VirtIO to provide better performance on systems with VirtIO paravirtualized network driver support.
MAC Address
Displays the default auto-generated random MAC address the VM receives. Enter a custom address to override the default.
Generate
Click to add a new randomized address in MAC Address.
NIC To attach
Select a physical interface from the dropdown list to associate with the VM.
Trust Guest Filters
Default setting is not enabled. Set this attribute to allow the virtual server to change its MAC address. As a consequence, the virtual server can join multicast groups. The ability to join multicast groups is a prerequisite for the IPv6 Neighbor Discovery Protocol (NDP). Setting Trust Guest Filters to “yes” has security risks because it allows the virtual server to change its MAC address and receive all frames delivered to this address.
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.
Add Disk Device Type Settings
Select Disk in Device Type in the Add device screen to see the disk settings including disk location, drive type, and disk sector size.
Select the drive type from the dropdown list. Options are AHCI or VirtIO.
Disk sector size
Select the disk sector size from the dropdown list or leave set as Default. Options are Default, 512 or 4096.
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.
Add Display Device Type Settings
Remote clients can connect to VM display sessions using a SPICE client, or by installing a 3rd party remote desktop server inside your VM.
SPICE clients are available from the SPICE Protocol site.
Select Display in Device Type in the Add device screen to see the display device settings.
Select the device type from the dropdown list. Display is the default setting.
Port
Enter the port number. You can assign 0, leave it empty for TrueNAS to assign a port when the VM is started, or set it to a fixed preferred port number.
Resolution
Select a screen resolution to use for VM display sessions.
Bind
Select an IP address to use for display sessions or use the default 0.0.0.0.
Password
Enter a password of no more than eight characters in length to automatically pass to the remote display session.
Web Interface
Select to enable connecting to the SPICE web interface.
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls. If you want the CD-ROM to be the first device checked assign it a lower number.
Add Raw File Device Type Settings
Select Raw File in Device Type in the Add device screen to see the raw file settings that include location, size of the file, disk sector size, and type.
Enter or use the to the left of /mnt to browse to the location of the file on the system.
Disk sector size
Select the disk sector size from the dropdown list or leave set as Default. Options are Default, 512 or 4096.
Mode
Select the drive type from the dropdown list. Options are AHCI or VirtIO.
Raw filesize
Enter the size of the file in GiB.
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.
Add PCI Passthrough Device Type Settings
Select PCI Passthrough Device in Device Type in the Add device screen to see the PCI passthrough device settings.
Depending upon the type of device installed in your system, you might see a warning: PCI device does not have a reset mechanism defined. You might experience inconsistent or degraded behavior when starting or stopping the VM.
Determine if you want to proceed with this action in such an instance.
Enter or select the device from the dropdown list of options. Enter as (bus#/slot#/fcn#).
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.
Add USB Passthrough Device Type Settings
Select USB Passthrough Device in Device Type in the Add device screen to see the USB passthrough device settings.
Enter or select the device from the dropdown list of options. If Specify custom is chosen, enter the required Vendor ID and Product ID.
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.