diff --git a/docset/winserver2025-ps/hyper-v/New-VM.md b/docset/winserver2025-ps/hyper-v/New-VM.md index 61109509b6..57dcc2caca 100644 --- a/docset/winserver2025-ps/hyper-v/New-VM.md +++ b/docset/winserver2025-ps/hyper-v/New-VM.md @@ -2,7 +2,7 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml Module Name: Hyper-V -ms.date: 12/20/2016 +ms.date: 08/13/2024 online version: https://learn.microsoft.com/powershell/module/hyper-v/new-vm?view=windowsserver2025-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: New-VM @@ -11,7 +11,6 @@ title: New-VM # New-VM ## SYNOPSIS - Creates a new virtual machine. ## SYNTAX @@ -20,85 +19,95 @@ Creates a new virtual machine. ``` New-VM [[-Name] ] [[-MemoryStartupBytes] ] [-BootDevice ] [-NoVHD] - [-SwitchName ] [-Path ] [-Version ] [-Prerelease] [-Experimental] - [[-Generation] ] [-Force] [-AsJob] [-CimSession ] [-ComputerName ] - [-Credential ] [-WhatIf] [-Confirm] [] + [-SwitchName ] [-Path ] [-SourceGuestStatePath ] [-Version ] + [-Prerelease] [-Experimental] [[-Generation] ] + [-GuestStateIsolationType ] [-Force] [-AsJob] [-CimSession ] + [-ComputerName ] [-Credential ] [-WhatIf] [-Confirm] [] ``` ### New VHD ``` -New-VM [[-Name] ] [[-MemoryStartupBytes] ] [-BootDevice ] [-SwitchName ] - -NewVHDPath -NewVHDSizeBytes [-Path ] [-Version ] [-Prerelease] - [-Experimental] [[-Generation] ] [-Force] [-AsJob] [-CimSession ] - [-ComputerName ] [-Credential ] [-WhatIf] [-Confirm] [] +New-VM [[-Name] ] [[-MemoryStartupBytes] ] [-BootDevice ] + [-SwitchName ] -NewVHDPath -NewVHDSizeBytes [-Path ] + [-SourceGuestStatePath ] [-Version ] [-Prerelease] [-Experimental] + [[-Generation] ] [-GuestStateIsolationType ] [-Force] [-AsJob] + [-CimSession ] [-ComputerName ] [-Credential ] [-WhatIf] + [-Confirm] [] ``` ### Existing VHD ``` -New-VM [[-Name] ] [[-MemoryStartupBytes] ] [-BootDevice ] [-SwitchName ] - -VHDPath [-Path ] [-Version ] [-Prerelease] [-Experimental] [[-Generation] ] - [-Force] [-AsJob] [-CimSession ] [-ComputerName ] [-Credential ] - [-WhatIf] [-Confirm] [] +New-VM [[-Name] ] [[-MemoryStartupBytes] ] [-BootDevice ] + [-SwitchName ] -VHDPath [-Path ] [-SourceGuestStatePath ] + [-Version ] [-Prerelease] [-Experimental] [[-Generation] ] + [-GuestStateIsolationType ] [-Force] [-AsJob] [-CimSession ] + [-ComputerName ] [-Credential ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The **New-VM** cmdlet creates a new virtual machine. +The `New-VM` cmdlet creates a new virtual machine. ## EXAMPLES ### Example 1 ```powershell -New-VM -Name "new 1" -MemoryStartupBytes 512MB +New-VM -Name "VM01" -MemoryStartupBytes 512MB ``` -This example creates a new virtual machine named new 1 that has 512 MB of memory. +This example creates a new virtual machine named `VM01` that has 512 MB of memory. ### Example 2 ```powershell -New-VM -Name "new 2" -MemoryStartupBytes 1GB -NewVHDPath d:\vhd\base.vhdx -NewVHDSizeBytes 40GB +New-VM -Name "VM01" -MemoryStartupBytes 1GB -NewVHDPath D:\vhd\base.vhdx -NewVHDSizeBytes 40GB ``` -This example creates a virtual machine named new 2 that has 1 GB of memory and that is connected to a new 40 GB virtual hard disk that uses the VHDX format. +This example creates a virtual machine named `VM01` that has 1 GB of memory and that is connected to +a new 40 GB virtual hard disk that uses the `VHDX` format. ### Example 3 ```powershell -New-VM -Name "new 3" -MemoryStartupBytes 1GB -VHDPath d:\vhd\BaseImage.vhdx +New-VM -Name "VM01" -MemoryStartupBytes 1GB -VHDPath D:\vhd\BaseImage.vhdx ``` -This example creates a virtual machine named new 3 that has 1 GB of memory and connects it to an existing virtual hard disk that uses the VHDX format. +This example creates a virtual machine named `VM01` that has 1 GB of memory and connects it to an +existing virtual hard disk that uses the `VHDX` format. ### Example 4 ```powershell -New-VM -Name "new 4" -MemoryStartupBytes 2GB -Credential (Get-Credential) -ComputerName HostServer01 +New-VM -Name "VM01" -MemoryStartupBytes 2GB -Credential (Get-Credential) -ComputerName HostServer01 ``` -This example asks for credentials, then creates a virtual machine named new 4, which has 2 GB of memory, on the server named HostServer01. +This example asks for credentials, then creates a virtual machine named `VM01`, which has 2 GB of +memory, on the server named `HostServer01`. ### Example 5 ```powershell -New-VM -Name "new 5" -Generation 1 -BootDevice CD -NoVHD +New-VM -Name "VM01" -Generation 1 -BootDevice CD -NoVHD ``` -This example creates a virtual machine named new 5. The machine doesn't have any VHD disk and is set to boot from CD. +This example creates a virtual machine named `VM01`. The machine doesn't have any VHD disks and is +set to boot from a CD. ### Example 6 ```powershell -$oldVM = Get-VM "old 1" +$oldVM = Get-VM "PreviousVM" $memory = (Get-VMMemory -VMName $oldVM.name).Startup $switch = (Get-VMNetworkAdapter -VMName $oldVM.name).SwitchName -New-VM -Name "new 6" -Generation $oldVM.Generation -MemoryStartupBytes $memory -SwitchName $switch +New-VM -Name "VM01" -Generation $oldVM.Generation -MemoryStartupBytes $memory -SwitchName $switch ``` -This example creates a virtual machine named new 6. The machine has the same generation and amount of assigned memory as the existing machine named old 1 and connects to the same network switch. +This example creates a virtual machine named `VM01`. The machine has the same generation and amount +of assigned memory as the existing machine named `PreviousVM` and connects to the same network +switch. ## PARAMETERS @@ -120,16 +129,25 @@ Accept wildcard characters: False ### -BootDevice -Specifies the device to use as the boot device for the new virtual machine. -Allowed values are **CD**, **Floppy**, **LegacyNetworkAdapter**, **IDE**, NetworkAdapter, and VHD. +Specifies the device to use as the boot device for the new virtual machine. Acceptable values are: + +- `CD` +- `Floppy` +- `LegacyNetworkAdapter` +- `IDE` +- `NetworkAdapter` +- `VHD` -When LegacyNetworkAdapter is specified, this configures the new virtual machine with a network adapter that can be used to perform a PXE boot and install an operating system from a network installation server. +When `LegacyNetworkAdapter` is specified, this configures the new virtual machine with a network +adapter that can be used to perform a PXE boot and install an operating system from a network +installation server. -Note: Generation 2 virtual machines do not support Floppy, LegacyNetworkAdapter or IDE. -Using these values with a Generation 2 virtual machine will cause an error. +Generation 2 virtual machines do not support `Floppy`, `LegacyNetworkAdapter` or `IDE`. Using these +values with a Generation 2 virtual machine will cause an error. -VHD and NetworkAdapter are new to Generation 2 virtual machines. -If you specify them on a Generation 1 virtual machine, then they are interpreted to be IDE and LegacyNetworkAdapter, respectively. +`VHD` and `NetworkAdapter` are new to Generation 2 virtual machines. If you specify them on a +Generation 1 virtual machine, then they are interpreted to be `IDE` and `LegacyNetworkAdapter` +respectively. ```yaml Type: BootDevice @@ -146,9 +164,10 @@ Accept wildcard characters: False ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) or +[Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -164,10 +183,9 @@ Accept wildcard characters: False ### -ComputerName -Specifies one or more Hyper-V hosts on which the virtual machine is to be created. -NetBIOS names, IP addresses, and fully qualified domain names are allowable. -The default is the local computer. -Use localhost or a dot (.) to specify the local computer explicitly. +Specifies one or more Hyper-V hosts on which the virtual machine is to be created. NetBIOS names, +IP addresses, and fully qualified domain names are allowable. The default is the local computer. +Use localhost or a dot (`.`) to specify the local computer explicitly. ```yaml Type: String[] @@ -192,15 +210,15 @@ Aliases: cf Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Credential -Specifies one or more user accounts that have permission to perform this action. -The default is the current user. +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. ```yaml Type: PSCredential[] @@ -216,6 +234,8 @@ Accept wildcard characters: False ### -Experimental +{{ Fill Experimental Description }} + ```yaml Type: SwitchParameter Parameter Sets: (All) @@ -230,6 +250,8 @@ Accept wildcard characters: False ### -Force +Forces the command to run without asking for user confirmation. + ```yaml Type: SwitchParameter Parameter Sets: (All) @@ -244,8 +266,10 @@ Accept wildcard characters: False ### -Generation -Specifies the generation, as an integer, for the virtual machine. -The values that are valid in this version of Windows are 1 and 2. +Specifies the generation, as an integer, for the virtual machine. Acceptable values are: + +- `1` +- `2` ```yaml Type: Int16 @@ -260,10 +284,33 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -GuestStateIsolationType + +Specifies the level of security for the virtual machine being created. Acceptable values are: + +- `TrustedLaunch`: Enables Trusted Launch security feature for the virtual machine. +- `VBS`: Enables Virtualization Based Security (VBS) for the virtual machine. +- `SNP`: Enables System and Network Protection (SNP) for the virtual machine. +- `TDX`: Enables Trusted Execution (TDX) for the virtual machine. +- `Disabled`: Disables all guest state isolation features for the virtual machine. + +```yaml +Type: GuestIsolationType +Parameter Sets: (All) +Aliases: +Accepted values: TrustedLaunch, VBS, SNP, TDX, Disabled + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -MemoryStartupBytes -Specifies the amount of memory, in bytes, to assign to the virtual machine. -The default value is 512 MB. +Specifies the amount of memory, in bytes, to assign to the virtual machine. The default value is +`512 MB`. ```yaml Type: Int64 @@ -279,8 +326,7 @@ Accept wildcard characters: False ### -Name -Specifies the name of the new virtual machine. -The default name is New virtual machine. +Specifies the name of the new virtual machine. The default name is New virtual machine. ```yaml Type: String @@ -297,8 +343,8 @@ Accept wildcard characters: False ### -NewVHDPath Creates a new virtual hard disk with the specified path and connects it to the new virtual machine. -Absolute paths are allowed. -If only a file name is specified, the virtual hard disk is created in the default path configured for the host. +Absolute paths are allowed. If only a file name is specified, the virtual hard disk is created in +the default path configured for the host. ```yaml Type: String @@ -314,7 +360,8 @@ Accept wildcard characters: False ### -NewVHDSizeBytes -Specifies the size of the dynamic virtual hard disk that is created and attached to the new virtual machine. +Specifies the size of the dynamic virtual hard disk that is created and attached to the new virtual +machine. ```yaml Type: UInt64 @@ -362,6 +409,8 @@ Accept wildcard characters: False ### -Prerelease +{{ Fill Prerelease Description }} + ```yaml Type: SwitchParameter Parameter Sets: (All) @@ -374,10 +423,30 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -SourceGuestStatePath + +Specifies the path to the guest state file for the virtual machine being created. Specifying the +guest state path allows for creation of a new virtual machine that has the same configuration and +state as the existing virtual machine. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -SwitchName -Specifies the friendly name of the virtual switch if you want to connect the new virtual machine to an existing virtual switch to provide connectivity to a network. -Hyper-V automatically creates a virtual machine with one virtual network adapter, but connecting it to a virtual switch is optional. +Specifies the friendly name of the virtual switch if you want to connect the new virtual machine to +an existing virtual switch to provide connectivity to a network. Hyper-V automatically creates a +virtual machine with one virtual network adapter, but connecting it to a virtual switch is +optional. ```yaml Type: String @@ -409,6 +478,8 @@ Accept wildcard characters: False ### -Version +{{ Fill Version Description }} + ```yaml Type: Version Parameter Sets: (All) @@ -423,8 +494,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -433,17 +503,22 @@ Aliases: wi Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS +### System.String + ## OUTPUTS ### Microsoft.HyperV.PowerShell.VirtualMachine