New-XenVM

Last published : Nov 12, 2026
Creates a new VM object.
Related information
VM cmdlets

Syntax

New-XenVM -HashTable <hashtable> [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>]
    [-WhatIf] [-Confirm] [-Async] [<CommonParameters>]
New-XenVM -Record <VM> [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>] [-WhatIf]
    [-Confirm] [-Async] [<CommonParameters>]
New-XenVM [-PassThru] [-NameLabel <string>] [-NameDescription <string>]
    [-PowerState {Halted | Paused | Running | Suspended | unknown}] [-UserVersion <long>]
    [-IsATemplate <bool>] [-SuspendVDI <XenRef[VDI]>] [-Affinity <XenRef[Host]>]
    [-MemoryTarget <long>] [-MemoryStaticMax <long>] [-MemoryDynamicMax <long>]
    [-MemoryDynamicMin <long>] [-MemoryStaticMin <long>] [-VCPUsParams <hashtable>]
    [-VCPUsMax <long>] [-VCPUsAtStartup <long>]
    [-ActionsAfterSoftreboot {soft_reboot | destroy | restart | preserve | unknown}]
    [-ActionsAfterShutdown {destroy | restart | unknown}]
    [-ActionsAfterReboot {destroy | restart | unknown}]
    [-ActionsAfterCrash {destroy | coredump_and_destroy | restart | coredump_and_restart | preserve | rename_restart | unknown}]
    [-PVBootloader <string>] [-PVKernel <string>] [-PVRamdisk <string>] [-PVArgs <string>]
    [-PVBootloaderArgs <string>] [-PVLegacyArgs <string>] [-HVMBootPolicy <string>]
    [-HVMBootParams <hashtable>] [-HVMShadowMultiplier <double>] [-Platform <hashtable>]
    [-PCIBus <string>] [-OtherConfig <hashtable>] [-LastBootCPUFlags <hashtable>]
    [-LastBootedRecord <string>] [-Recommendations <string>] [-XenstoreData <hashtable>]
    [-HaAlwaysRun <bool>] [-HaRestartPriority <string>] [-Tags <string[]>]
    [-BlockedOperations {snapshot | clone | copy | create_template | revert | checkpoint | snapshot_with_quiesce | provision | start | start_on | pause | unpause | clean_shutdown | clean_reboot | hard_shutdown | power_state_reset | hard_reboot | suspend | csvm | resume | resume_on | pool_migrate | migrate_send | get_boot_record | send_sysrq | send_trigger | query_services | shutdown | call_plugin | changing_memory_live | awaiting_memory_live | changing_dynamic_range | changing_static_range | changing_memory_limits | changing_shadow_memory | changing_shadow_memory_live | changing_VCPUs | changing_VCPUs_live | changing_NVRAM | assert_operation_valid | data_source_op | update_allowed_operations | make_into_template | import | export | metadata_export | reverting | destroy | create_vtpm | sysprep | unknown}]
    [-ProtectionPolicy <XenRef[VMPP]>] [-IsSnapshotFromVmpp <bool>]
    [-SnapshotSchedule <XenRef[VMSS]>] [-IsVmssSnapshot <bool>]
    [-Appliance <XenRef[VM_appliance]>] [-StartDelay <long>] [-ShutdownDelay <long>]
    [-Order <long>] [-SuspendSR <XenRef[SR]>] [-Version <long>] [-GenerationId <string>]
    [-HardwarePlatformVersion <long>] [-HasVendorDevice <bool>] [-ReferenceLabel <string>]
    [-DomainType {hvm | pv | pv_in_pvh | pvh | unspecified | unknown}]
    [-NVRAM <hashtable>] [-BestEffort] [-SessionOpaqueRef <string>] [-WhatIf] [-Confirm]
    [-Async] [<CommonParameters>]

Description

Creates a new VM object.
VM.create: NOT RECOMMENDED! VM.clone or VM.copy (or VM.import) is a better choice in almost all situations. The standard way to obtain a new VM is to call VM.clone on a template VM, then call VM.provision on the new clone. Caution: if VM.create is used and then the new VM is attached to a virtual disc that has an operating system already installed, then there is no guarantee that the operating system will boot and run. Any software that calls VM.create on a future version of this API may fail or give unexpected results. For example this could happen if an additional parameter were added to VM.create. VM.create is intended only for use in the automatic creation of the system VM templates. It creates a new VM instance, and returns its handle.
VM: A virtual machine (or 'guest').

Parameters

-ActionsAfterCrash

action to take if the guest crashes
Attribute Value
Type on_crash_behaviour
Required False
Position Named
Accepts pipeline input False
Accepted values destroy, coredump_and_destroy, restart, coredump_and_restart, preserve, rename_restart, unknown

-ActionsAfterReboot

action to take after the guest has rebooted itself
Attribute Value
Type on_normal_exit
Required False
Position Named
Accepts pipeline input False
Accepted values destroy, restart, unknown

-ActionsAfterShutdown

action to take after the guest has shutdown itself
Attribute Value
Type on_normal_exit
Required False
Position Named
Accepts pipeline input False
Accepted values destroy, restart, unknown

-ActionsAfterSoftreboot

action to take after soft reboot
Attribute Value
Type on_softreboot_behavior
Required False
Position Named
Accepts pipeline input False
Accepted values soft_reboot, destroy, restart, preserve, unknown

-Affinity

A host which the VM has some affinity for (or NULL). This is used as a hint to the start call when it decides where to run the VM. Resource constraints may cause the VM to be started elsewhere.
Attribute Value
Type XenRef[Host]
Required False
Position Named
Accepts pipeline input False

-Appliance

the appliance to which this VM belongs
Attribute Value
Type XenRef[VM_appliance]
Required False
Position Named
Accepts pipeline input False

-Async

If set, the operation runs asynchronously and returns a Task object that can be used to track its progress.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-BestEffort

If set, the cmdlet continues processing further objects instead of throwing a terminating error when an operation fails for one object.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-BlockedOperations

List of operations which have been explicitly blocked and an error code
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False
Accepted values snapshot, clone, copy, create_template, revert, checkpoint, snapshot_with_quiesce, provision, start, start_on, pause, unpause, clean_shutdown, clean_reboot, hard_shutdown, power_state_reset, hard_reboot, suspend, csvm, resume, resume_on, pool_migrate, migrate_send, get_boot_record, send_sysrq, send_trigger, query_services, shutdown, call_plugin, changing_memory_live, awaiting_memory_live, changing_dynamic_range, changing_static_range, changing_memory_limits, changing_shadow_memory, changing_shadow_memory_live, changing_VCPUs, changing_VCPUs_live, changing_NVRAM, assert_operation_valid, data_source_op, update_allowed_operations, make_into_template, import, export, metadata_export, reverting, destroy, create_vtpm, sysprep, unknown

-Confirm

Prompts for confirmation before running the cmdlet.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False
Aliases cf

-DomainType

The type of domain that will be created when the VM is started
Attribute Value
Type domain_type
Required False
Position Named
Accepts pipeline input False
Accepted values hvm, pv, pv_in_pvh, pvh, unspecified, unknown

-GenerationId

Generation ID of the VM
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-HVMBootParams

HVM boot params
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-HVMBootPolicy

HVM boot policy
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-HVMShadowMultiplier

multiplier applied to the amount of shadow that will be made available to the guest
Attribute Value
Type double
Required False
Position Named
Accepts pipeline input False

-HaAlwaysRun

if true then the system will attempt to keep the VM running as much as possible.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-HaRestartPriority

has possible values: "best-effort" meaning "try to restart this VM if possible but don't consider the Pool to be overcommitted if this is not possible"; "restart" meaning "this VM should be restarted"; "" meaning "do not try to restart this VM"
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-HardwarePlatformVersion

The host virtual hardware platform version the VM can run on
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-HasVendorDevice

When an HVM guest starts, this controls the presence of the emulated C000 PCI device which triggers Windows Update to fetch or update PV drivers.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-HashTable

A hashtable of field names to values, from which to create the VM.
Attribute Value
Type hashtable
Required True
Position Named
Accepts pipeline input False

-IsATemplate

true if this is a template. Template VMs can never be started, they are used only for cloning other VMs
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-IsSnapshotFromVmpp

true if this snapshot was created by the protection policy
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-IsVmssSnapshot

true if this snapshot was created by the snapshot schedule
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-LastBootCPUFlags

describes the CPU flags on which the VM was last booted
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-LastBootedRecord

marshalled value containing VM record at time of last boot
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-MemoryDynamicMax

Dynamic maximum (bytes)
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-MemoryDynamicMin

Dynamic minimum (bytes)
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-MemoryStaticMax

Statically-set (i.e. absolute) maximum (bytes). The value of this field at VM start time acts as a hard limit of the amount of memory a guest can use. New values only take effect on reboot.
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-MemoryStaticMin

Statically-set (i.e. absolute) mininum (bytes). The value of this field indicates the least amount of memory this VM can boot with without crashing.
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-MemoryTarget

Dynamically-set memory target (bytes). The value of this field indicates the current target for memory available to this VM.
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-NVRAM

initial value for guest NVRAM (containing UEFI variables, etc). Cannot be changed while the VM is running
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-NameDescription

a notes field containing human-readable description
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-NameLabel

a human-readable name
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Order

The point in the startup or shutdown sequence at which this VM will be started
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-OtherConfig

additional configuration
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-PCIBus

PCI bus path for pass-through devices
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-PVArgs

kernel command-line arguments
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-PVBootloader

name of or path to bootloader
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-PVBootloaderArgs

miscellaneous arguments for the bootloader
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-PVKernel

path to the kernel
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-PVLegacyArgs

to make Zurich guests boot
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-PVRamdisk

path to the initrd
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-PassThru

If set, the cmdlet returns the affected object. By default the cmdlet does not generate any output.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-Platform

platform-specific configuration
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-PowerState

Current power state of the machine
Attribute Value
Type vm_power_state
Required False
Position Named
Accepts pipeline input False
Accepted values Halted, Paused, Running, Suspended, unknown

-ProtectionPolicy

Ref pointing to a protection policy for this VM
Attribute Value
Type XenRef[VMPP]
Required False
Position Named
Accepts pipeline input False

-Recommendations

An XML specification of recommended values and ranges for properties of this VM
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Record

An existing VM record whose fields are used to create the new object.
Attribute Value
Type VM
Required True
Position Named
Accepts pipeline input False

-ReferenceLabel

Textual reference to the template used to create a VM. This can be used by clients in need of an immutable reference to the template since the latter's uuid and name\_label may change, for example, after a package installation or upgrade.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-SessionOpaqueRef

The session object on which to run the cmdlet. This overrides the default session and lets you target a specific open XenServer connection.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-ShutdownDelay

The delay to wait before proceeding to the next order in the shutdown sequence (seconds)
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-SnapshotSchedule

Ref pointing to a snapshot schedule for this VM
Attribute Value
Type XenRef[VMSS]
Required False
Position Named
Accepts pipeline input False

-StartDelay

The delay to wait before proceeding to the next order in the startup sequence (seconds)
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-SuspendSR

The SR on which a suspend image is stored
Attribute Value
Type XenRef[SR]
Required False
Position Named
Accepts pipeline input False

-SuspendVDI

The VDI that a suspend image is stored on. (Only has meaning if VM is currently suspended)
Attribute Value
Type XenRef[VDI]
Required False
Position Named
Accepts pipeline input False

-Tags

user-specified tags for categorization purposes
Attribute Value
Type string[]
Required False
Position Named
Accepts pipeline input False

-UserVersion

Creators of VMs and templates may store version information here.
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-VCPUsAtStartup

Boot number of VCPUs
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-VCPUsMax

Max number of VCPUs
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-VCPUsParams

configuration parameters for the selected VCPU policy
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-Version

The number of times this VM has been recovered
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False
Aliases wi

-XenstoreData

data to be inserted into the xenstore tree (/local/domain/<domid>/vm-data) after the VM is created.
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

Inputs

  • None

Outputs

  • VM
  • Task
  • void

Examples

Example 1: Create a VM from a table of fields

PS> New-XenVM -HashTable @{ name_label = "Demo VM" } -PassThru
The keys are the API's field names, so this form reads the same for every class whatever fields it happens to have. -PassThru returns the new VM.

Example 2: Create a VM from a table of fields

PS> New-XenVM -HashTable @{
        name_label        = "web-03"
        memory_static_max = "2147483648"
        VCPUs_max         = "2"
        VCPUs_at_startup  = "2"
    } -PassThru
The keys are the API's field names, so anything the class accepts at creation can be set in one call. In practice most VMs are made by cloning a template rather than built from fields like this.

Example 3: Create a VM from parameters

PS> New-XenVM -NameLabel "new value" -PassThru
The same thing with one parameter per field, which is the form that tab-completes. Get-Help New-XenVM -Full lists them all.
  • VM cmdlets
  • Class: VM
  • Using the XenServer PowerShell module