ImageX Command-Line Options
ImageX is a command-line tool in Windows Vista that you can use to create and manage Windows image (.wim) files. A .wim file contains one or more volume images, disk volumes that contain images of an installed Windows operating system.
To modify your volume images, you must install the Windows Imaging File System Filter (WIM FS Filter) driver on a computer running Windows XP with Service Pack 2 (SP2), Windows Server 2003 with Service Pack 1 (SP1), or Windows Vista. Installing the WIM FS Filter driver enables you to mount a .wim file as if it were a directory and to browse, to copy, to paste, and to edit the volume images from a file management tool, such as Windows Explorer, without extracting or recreating the image.
Important
You must run each of these command-line options individually. If you do not provide a location for your captured .wim file, the process automatically creates it in your ImageX directory. For example, if you enter Data.wim instead of D:\Imaging\Data.wim while using the /capture option, the Data.wim file appears in your ImageX directory.
ImageX Command-Line Options
ImageX command-line options use the following conventions.
imagex [flags] {/append | /apply | /capture | /delete | /dir | /export | /info | /split | /mount | /mountrw | /unmount} [parameters]
The following list shows the valid syntax used for each imagex operation type.
imagex /append image_path image_file {"description"} {/boot | /check | /config configuration_file.ini | /scroll | /verify}
imagex /apply image_file image_number image_name image_path {/check | /ref | /scroll | /verify}
imagex /capture image_path image_file "name" {"description"} {/boot | /check | /compress [type] | /config | /flags "EditionID" | /norpfix | /scroll | /verify}
imagex /delete image_file image_number image_name {/check}
imagex /dir image_file image_number image_name
imagex /export src_file src_number src_name dest_file dest_name {/boot | /check | /compress [type] | /ref [splitwim.swm]}
imagex /info img_file [img_number | img_name] [new_name] [new_desc] {/boot | /check}
imagex /mount image_file image_number image_name image_path {/check}
imagex /mountrw image_file image_number image_name image_path {/check}
imagex /split image_file dest_file size {/check}
imagex /unmount image_path {/commit}
| Operation | Description | ||
|---|---|---|---|
imagex /append image_path image_file {"description"}{/boot | /check | /config configuration_file.ini | /scroll | /verify} |
Appends a volume image to an existing Windows image (.wim) file. Creates a single instance of the file, comparing it against the resources that already exist in the .wim file, so you do not capture the same file twice.
Important The .wim file can have only one assigned compression type; therefore, you can append only files with the same compression type. image_path Specifies the name and the location of the existing .wim file to append. image_file Specifies the name and the location of the volume image that appends the existing file. "description" Specifies the text that provides additional reference information. The straight quotation marks are required. You can also set the following options: /boot Marks a volume image as bootable. This option applies only to Windows PE images. Only one volume image can be marked as bootable in a .wim file. /check Checks the integrity of the .wim file. If not provided, existing checks are removed. /config configuration_file.ini Specifies the name and the location of the configuration file. You can rename this file as necessary. /scroll Scrolls output for redirection. /verify Enables file resource verification by checking for errors and file duplication. For example, |
||
imagex /apply image_file image_numberimage_nameimage_path {/check | /ref | /scroll | /verify} |
Applies a volume image to a specified drive. Important You must run this option from Windows PE. image_file Specifies the name and the location of the volume image applied to the directory. image_number Specifies the number that references the specific volume within the .wim file. image_name Specifies the name that identifies the image in the .wim file. image_path Specifies the file path where the image will be applied. You must create all hard disk partitions before beginning this process, unless you run this option by using a script. If you use the /apply option for a directory structure, the option will include the specified directory, including all subdirectories and files. Important You must include the parent directory for the /apply option. Otherwise, when the image is applied, it will overwrite everything in that location. For example, if you apply the image to drive C, the /apply option overwrites everything that exists in drive C with your image files. To automate the creation of a directory, you must add the mkdir target_directory command to your script before executing imagex /apply. You can also set the following options: /check Checks the integrity of the .wim file. If not provided, existing checks are removed. /ref splitwim.swm Enables the reference of split .wim files (SWMs). splitwim.swm is the name and location of additional split files. Wildcards are accepted. /scroll Scrolls output for redirection. /verify Enables file resource verification by checking for errors and file duplication. For example, |
||
imagex /capture image_path image_file "name" {"description"} {/boot | /check | /compress [type] | /config | /flags "EditionID" | /norpfix | /scroll | /verify} |
Captures a volume image from a drive to a new .wim file. Captured directories include all subfolders and data. You cannot capture an empty directory. A directory must contain at least one file. Note ImageX does not support extended attributes. ImageX will ignore extended attributes during a capture operation. During the capture operation, fast compression is automatically applied. If you require a different compression type, use the /compress option. image_path Specifies the name and the location of the volume image for capture. image_file Specifies the name and the location of the new .wim file. "name" Specifies the name of the new .wim file. This value is required. The straight quotation marks are required. "description" Specifies the text that provides additional reference information. This value is optional. The straight quotation marks are required. You can also set the following options: /boot Marks a volume image as bootable. Available only for Windows PE images. Only one volume image can be marked as bootable within a .wim file. /check Checks the integrity of the .wim file. If not provided, existing checks are removed. /compress [maximum | fast | none] Specifies the type of compression used for the initial capture operation. The maximum option provides the best compression but takes the longest time to capture the image. The fast option provides faster image compression but the resulting files are larger than those compressed with the maximum option. This is also the default compression type, used if you leave this parameter blank. The none option does not compress the captured image at all. Note While the compression type that you choose affects the capture time, it only slightly affects the apply time. /config configuration_file.ini Specifies the name and the location of the configuration file. You can rename this file, as necessary. Note If you rename your Configuration_list.ini file to Wimscript.ini and store it in your ImageX directory (where the ImageX.exe file is located), it will automatically run when you run the /capture option, without requiring you to use the /config option. /flags "EditionID" Specifies the version of Windows you are about to capture. The /flags value is required if you are going to re-deploy a custom Install.wim with Windows Setup. The straight quotation marks are required. This flag is not required if you deploy the image, by using ImageX. Valid EditionID values include: HomeBasic HomePremium Starter Ultimate Business Enterprise ServerDatacenter ServerEnterprise ServerStandard /norpfix Disables reparse point tag fixup. If set, reparse points that resolve to paths outside of image_path will not be captured. /scroll Scrolls output for redirection. /verify Enables file resource verification, by checking for errors and file duplication. Note The /verify option will affect the overall capture time. During a capture operation, the progress bar indicates the status of the capture operation only, not the verify operation. When the capture is complete, the verify process begins. This process takes time even though the progress bar shows 100 percent. For example, |
||
imagex /delete image_fileimage_numberimage_name {/check} |
Deletes the specified volume image from a .wim file with multiple volume images. This option deletes only the metadata entries and XML entries. It does not delete the stream data and does not optimize the .wim file. Once the file is mounted, you can view, but not modify, all the information contained in the directory. If you do not specify the parameters to mount, this option will list all mounted images. image_file Specifies the name and the location of the .wim file specified for deletion. image_number Specifies the number that references the specific volume within the .wim file. Important You must run this option from Windows PE. There must always be at least one volume image in a .wim file, so you can delete a volume image only if more than one image exists. image_name Specifies the name that references the image in the .wim file. You can also set the following option: /check Checks the integrity of the .wim file. If not provided, existing checks are removed. For example, |
||
imagex /dir image_fileimage_numberimage_name |
Displays a list of the files and folders within a specified volume image. image_file Specifies the name and the location of the volume image for review. If you do not provide a volume image, this option returns a directory listing for all volume images in the .wim file. image_number Specifies the number that references the specific volume within the .wim file. image_name Specifies the name that references the image in the .wim file. For example, |
||
imagex /export src_filesrc_numbersrc_name dest_file dest_name {/boot | /check | /compress [type] | /ref [splitwim.swm]} |
Exports a copy of the specified .wim file to another .wim file. The source and destination files must use the same compression type. You can also optimize an image by exporting to a new image file. When you modify an image, ImageX stores additional resource files that increase the overall size of the image. Exporting the image will remove unnecessary resource files. Important You must run this option from Windows PE. Additionally, you must ensure that you have enough disk space for the /export option to run. If you run out of disk space while the /export option runs, you might corrupt the Destination.wim file. src_file Specifies the file path of the .wim file that contains the image to be copied src_number Specifies the number that references the specific volume within the .wim file. src_name Specifies the name that identifies the image in the source .wim file. dest_file Specifies the file path of the .wim file that will receive the image copy. dest_name Specifies the unique name for the image in the destination .wim file. You can also set the following options: /boot Marks a volume image as bootable. Available only for Windows PE images. Only one volume image can be marked as bootable within a .wim file. /check Checks the integrity of the .wim file. If not provided, existing checks are removed. /compress [maximum | fast | none] Specifies the type of compression used for the initial capture operation. The maximum option provides the best compression but takes the longest time to capture the image. The fast option provides faster image compression but the resulting files are larger than those compressed with the maximum option. This is also the default compression type, used if you leave this parameter blank. The none option does not compress the captured image at all. /ref splitwim.swm Enables the reference of split .wim files (SWMs). splitwim.swm is the name and location of additional split files. Wildcards are accepted. For example, |
||
imagex /info img_file[img_number | img_name] [new_name] [new_desc] {/boot | /check} |
Returns the stored XML descriptions for the specified .wim file, including but not limited to the total file size, the image index number, the directory count, file count, and a description. image_file Specifies the name and the location of the .wim file for XML data review. image_number Specifies the number that identifies an image in the .wim file. image_name Specifies the name that identifies an image in the .wim file. new_name Specifies the new unique name for the specified image. new_desc Specifies the new description for the specified image. You can also set the following options: /boot Marks a volume image as bootable. Available only for Windows PE images. Only one volume image can be marked as bootable within a .wim file. /check Checks the integrity of the .wim file. If not provided, existing checks are removed. For example, |
||
imagex /mount image_fileimage_numberimage_nameimage_path {/check} |
Mounts a .wim file from Windows XP with Service Pack 2 (SP2), Windows Server 2003 with Service Pack 1 (SP1), or Windows Vista with read-only permission to a specified directory. Once the file is mounted, you may view, but not modify, all the information contained in the directory. Important You must install the WIM FS filter before you can mount an image. image_file Specifies the path of the .wim file containing the specified image. image_number Specifies the number that references the specific volume within the .wim file. image_name Specifies the name that references the image in the .wim file. image_path Specifies the file path where the specified image will be mounted. You can also set the following flag: /check Checks the integrity of the .wim file. If not provided, existing checks are removed. For example, |
||
imagex /mountrw image_fileimage_numberimage_nameimage_path {/check} |
Mounts a .wim file from Windows XP with Service Pack 2 (SP2), Windows Server 2003 with Service Pack 1 (SP1), or Windows Vista with read/write permission to a specified directory. Once the file is mounted, you can view and modify all the information contained in the directory. Important You must install the WIM FS filter before you can mount an image. The /mountrw option requires exclusive access to the .wim file; therefore, you cannot use the /mountrw option if an image is currently mounted using the /mount option or the /mountrw option. Important You must not mount an image to the parent or the subdirectories of an already-mounted directory. Upon mounting an image to a directory that contains files, the existing files will be masked until you run the /unmount option. Additionally, you must not mount your image to Windows reserved folders. image_file Specifies the name and location of the .wim file to mount with read/write permission. image_number Specifies the number that references the specific volume within the .wim file. image_name Specifies the name that references the image in the .wim file. image_path Specifies the file path where the specified image will be mounted. You can also set the following option: /check Checks the integrity of the .wim file. If not provided, existing checks are removed. For example, |
||
imagex /split image_filedest_filesize {/check} |
Splits an existing .wim file into multiple read-only split .wim files (.swm). Important You must run this option from Windows PE. image_file Specifies the name and location of the .wim file to split. dest_file Specifies the file path of the split files. size Specifies the maximum size in megabytes (MB) for each created file. This option generates the .swm files into the specified directory, naming each file the same as the specified image_file, but with an appended number and the .swm file-name extension. For example, if you choose to split a file named Data.wim, this option creates a Data.swm file, a Data2.swm file, a Data3.swm file, and so on, defining each portion of the split .wim file. You can also set the following option: /check Checks the integrity of the .wim file. If not provided, existing checks are removed. For example, |
||
imagex /unmount image_path {/commit} |
Unmounts the mounted image from a specified directory. Important Confirm that you have enough hard disk space to add the files for your image. You must account for the size of the files that you add to the .wim file, plus any increase in file size due to the modification of existing files, minus any files that you deleted, before performing the /commit option. If you do not have enough hard disk space, an error will occur. image_path Specifies the complete directory location to unmount the files. If you do not specify a directory, this option will list all mounted images. Important If you use the /unmount option without the /commit option, your changes will be discarded. To be able to save your changes, you must mount the image by using the /mountrw option and use the /commit option when unmounting the image. For example, |
.gif)
Important/verify and /check Options
The /verify and /check options provide file verification and data integrity support for .wim files.
The /verify option verifies cache writes and checks for errors and file duplication. The /verify option does not support disk-flushing, write-through, or bypass system-caching. During a capture operation, the /verify option reads the captured file back and compares it, byte by byte, with the original captured file. During an apply operation, the /verify option re-hashes the applied file and compares it with the hash generated during a capture operation.
The /check option is designed to detect corruption of a .wim file. If the /check option is not set during a capture operation, the flag is ignored during an apply operation. During a capture operation, the /check option generates and stores a series of hashes for every 10-megabyte (MB) data block of the .wim file. During an apply operation, the /check option hashes and verifies the 10-MB blocks against the hashes stored during the capture operation.
The /verify and /check option will affect performance during apply operations. It is recommended that you use both the /verify and /check options for optimal image validation and data integrity.
ImageX Error Codes
| Error Code | Description |
|---|---|
0 |
Successful |
1 |
Invalid command-line option |
2 |
WIMGAPI failure |
3 |
Invalid configuration script |
4 |
Access denied, requires administrator privileges |