vhdutil

manipulate virtual disk and ISO images 

Command

SYNOPSIS

vhdutil -l [-j]

vhdutil -a iso/vhd/vhdx-file [-j]

vhdutil -d iso/vhd/vhdx-file

vhdutil -i iso/vhd/vhdx-file [-j]

vhdutil -c vhd/vhdx-file [-x] [-f] [-s MaxSize] [-j]

vhdutil -p vhd/vhdx-file [-j]

vhdutil -e vhd/vhdx-file -s NewSize [-j]

vhdutil -r vhd/vhdx-file -s NewSize [-j]

vhdutil -y vhd/vhdx-file -t vhd/vhdx-mirror-file [-j]

DESCRIPTION

vhdutil is a scriptable interface around the Windows 7 Virtual Hard Disk API. It permits some basic operations such as attaching, detaching, creating, resizing of virtual images. Windows 8 added VHDX file format and some ability to attach ISO images to the Virtual Hard Disk APIs. The command does not have a manifest requiring elevation, but many operations will simply give a permission denied without SE_MANAGE_VOLUME_PRIVILEGE asserted which probably requires elevation.

Options

-l [-j] 

List all attached images. Given that there is a lot of information to display it is presented on multiple lines which can be hard to parse. When paired with option -j the listing will be in JSON format.

Non-elevated process can enumerate attached images - but a different algorithm is used which results in a slightly different output format. 

$ vhdutil -l
VHDX Virtual Disk:      C:/vhds/my.vhdx  //./PHYSICALDRIVE1
        Partition 1: //?/Volume{9d68c9c4-0000-0000-0000-010000000000}/
        Partition 2: //?/Volume{9d68c9c4-0000-0000-0000-110000000000}/
ISO Image:      C:/iso/FreeBSD-11.1-source.iso  //./CDROM2
        //?/Volume{235d0755-7479-11ea-a4f9-0023ae82baa1}/
-a iso/vhd/vhdx-file [-j] 

Attach the specified virtual disk or ISO image and display interesting information about the Windows volumes created. The -j option will cause the output to be in a more parsable JSON format.

It appears to be possible to attach a read only ISO image more than once, while a read/write virtual disk image will show the image file as busy on attempted reattach. 

$ vhdutil -a C:/iso/FreeBSD-11.1-source.iso
ISO Image:      C:/iso/FreeBSD-11.1-source.iso  //./CDROM2
        //?/Volume{235d0755-7479-11ea-a4f9-0023ae82baa1}/
$ vhdutil -a C:/iso/FreeBSD-11.1-source.iso
ISO Image:      C:/iso/FreeBSD-11.1-source.iso  //./CDROM3
        //?/Volume{dd9f364f-7e86-11ea-a4f9-0023ae82baa1}/
-d iso/vhd/vhdx-file 

Detach an attached image file. If the atached volume is also mounted on a drive letter or directory it will be dismounted. If an ISO image is attached twice, the first discovered image file is detached.

-i vhd/vhdx-file [-j] 

Display information about the VHD or VHDX file in text or JSON format. Some information will be displayed about ISO files, but the main intent was to see information about virtual disks.

-c vhd/vhdx-file [-x] [-s MaxSize] [-j] 

Create a new and empty VHD or -x VHDX disk image. The -s MaxSize option specifies how large the disk image may grow for dynamiclly sized disk images or (-f) the full allocated size. The -f instructions the command to use fixed size full allocation for the image.

Windows 7 will fail if the -x is specified.

Create a dynamically sized VHDX file that can grow to 2GB 

$ vhdutil -c c:/vhds/new.vhdx -x -s 2147483648
Virtual Disk (VHDX Virtual Disk): c:/vhds/new.vhdx
        Virtual Size: 2147483648
        Physical Size: 4194304
        Block Size: 33554432
        Sector Size: 512
        Device GUID: {BDED4A85-547D-4B8B-A356-6B225C8656A0}
-p vhd/vhdx-file [-j] 

Compact a dynamically sized virtual disk image using file system agnostic compaction (looks for blocks of zeros). i.e. the disk is not attached and the compaction will fail if the image is already attached.

Compaction can be a lengthy operation. A progress meter may be presented for longer operations.

It is safe to interrupt compaction.

-e vhd/vhdx-file [-s NewSize] [-j] 

Expand a virtual disk. May be used on either a dynamically or fixed sized disk. -s NewSize is used to specify the disk image's new size or new maximum size.

Expansion can be a lengthy operation. A progress meter may be presented for longer operations.

-r vhd/vhdx-file [-s NewSize] [-j] 

Resize a virtual disk. May be used on either a dynamically or fixed sized disk but will invalidate any differencing chain that exists. -s NewSize is used to specify the disk image's new size or new maximum size. If no size is given this is similar to using -e to compact to minimum size.

Resizing can be a lengthy operation. A progress meter may be presented for longer operations.

Windows 7 will fail as ResizeVirtualDisk is a Windows 8 and later API.

-y existing-vhd/vhdx-file -t mirrored-vhd/vhdx-file [-j] 

This option uses MirrorVirtualDisk to copy an existing VHD or VHDX file followed by BreakMirrorVirtualDisk to sever the connection to the parent virtual image.

Resizing can be a lengthy operation. A progress meter may be presented for longer operations.

Windows 7 will fail as MirrorVirtualDisk and BreakMirrorVirtualDisk are Windows 8 and later API.

[-j] 

Many options accept an optional [-j] to display successful results in JSON format. Check for failure in program exit status.

DIAGNOSTICS

Possible exit status values are:

0 

Successful completion.

1 

Failure due to any of the following:

— inability to open the input file
— file in use
— permission denied
— any Windows Virtual Disk API failure

PORTABILITY

Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022.

AVAILABILITY

PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Commands:
mount, umount

PTC MKS Toolkit 10.4 Documentation Build 39.