ImageX Technical Reference (Standard 8)

7/8/2014

Review the use, syntax, options, and parameters of ImageX for Windows Embedded 8 Standard (Standard 8).

ImageX is a command-line tool that works with Windows image (.wim) files. A .wim file contains one or more volume images for a Windows Embedded 8 Standard (Standard 8) OS, while a volume image represents the captured volume or partition of a Standard 8 OS. The main purpose of ImageX is to capture, modify, and apply images for deployment in a manufacturing or corporate IT environment.

Warning

ImageX is not redistributable and is deprecated. The functionality previously provided by ImageX can be found in Deployment Image Servicing and Management (DISM). See Deployment Image Servicing and Management (DISM) Technical Reference for more information on DISM.

You typically use ImageX with the Windows Imaging File System (WIM FS Filter) driver. The WIM FS Filter driver supports mounting an image as if it were a directory where you can browse, copy, paste, and edit the files from a file-management tool, such as Windows Explorer, without extracting or recreating the image. Typically, you use ImageX in a Windows Preinstallation Environment (Windows PE) 4.0 environment during image-based deployments.

To modify your volume images, you must install the WIM FS Filter on a computer that is running Windows 7 Service Pack 1 (Windows 7 SP1), Windows 8, or Windows Embedded 8 Standard (Standard 8).

Note

If you do not provide a location for your captured .wim file, the process automatically creates the .wim file in the ImageX directory.

Syntax

imagex.exe
    [/scroll]
    [/logfile <log_file.log>]
    [/append | /apply | /capture | /delete | /dir | /export | /info | /split | /mount | /mountrw | /remount | /commit | /unmount | /cleanup]

    /append
        <image_path>
        <image_file>
        <"image_name">
        [<"description">]
        [/boot]
        [/check]
        [/config <configuration_file.ini>]
        [/norpfix]
        [/temp <temp_files_path>]
        [/verify]

    /apply
        <image_file>
        {<image_number> | <image_name>}
        <image_path>
        [/check]
        [/norpfix]
        [/ref <split_wim_file.swm>]
        [/temp <temp_files_path>]
        [/verify]

    /capture
        <image_path>
        <image_file>
        <"image_name">
        [<"description">]
        [/boot]
        [/check]
        [/compress [{maximum | fast | none}]]
        [/config <configuration_file.ini>]
        [/norpfix]
        [/temp <temp_files_path>]
        [/verify]

    /delete
        <image_file>
        {<image_number> | <image_name>}
        [/check]
        [/temp <temp_files_path>]

    /dir
        <image_file>
        {<image_number> | <image_name>}

    /export
        <src_file>
        {<src_number> | <src_name>}
        <dest_file>
        <dest_name>
        [/boot]
        [/check]
        [/compress [{maximum | fast | none}]]
        [/ref <split_wim_file.swm>]
        [/temp <temp_files_path>]

    /info
        <image_file>
        [{image_number | image_name}]
        [new_name]
        [new_desc]
        [/boot]
        [/check]
        [/temp <temp_files_path>]
        [/xml]

    /split
        <image_file>
        <dest_file>
        <size>
        [/check]

    /mount
        <image_file>
        {<image_number> | <image_name>}
        <image_path>
        [/check]
        [/optimize]

    /mountrw
        <image_file>
        {<image_number> | <image_name>}
        <image_path>
        [/check]
        [/optimize]

    /remount
        [<image_path>]

    /commit
        <mount_path>
        [<"image_name">]
        [/append]
        [/temp <temp_files_path>]

    /unmount
        <image_path>
        [/commit]

Where to Find ImageX

You can find ImageX at one of the following locations where drive C is the drive on which you installed the Standard 8 Toolkit and drive E is a DVD drive that contains the Standard 8 installation media. Depending on your device architecture, replace <device_architecture> with x86 or AMD64.

• C:\Program Files\Windows Embedded 8 Standard\Toolset\Windows Deployment Tools\Deployment Tools\<device_architecture>\DISM
• C:\Program Files (x86)\Windows Embedded 8 Standard\Toolset\Windows Deployment Tools\Deployment Tools\<device_architecture>\DISM
• E:\Windows Embedded 8 Standard\Toolset\Windows Deployment Tools\Deployment Tools\<device_architecture>\DISM

Command-Line Options and Parameters

Option	Description
/scroll	Scrolls output for redirection.
/logfile	Specifies the name and location of a simple, text-based file for logging ImageX actions.
/append	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 occur in the .wim file so that you do not capture the same file twice. This command must be run from Windows Preinstallation Environment (Windows PE) 4.0. Caution: Make sure that you have sufficient disk space for the /append command to run. If you run out of disk space while the command executes, you may corrupt the appended .wim file. Note: The .wim file can have only one assigned compression type. Therefore, you can only append files that have the same compression type. <image_path> The name and location of the existing .wim file to append. <image_file> The name and location of the volume image that appends the existing file. <"image_name"> The name that identifies the image in the .wim file. <"description"> The text that provides additional reference information. The straight quotation marks are required. The following code example shows how to use the /append option. imagex /append d: d:\imaging\data.wim "Drive D" /verify
/apply	Applies a volume image to a specified drive. You must run this command from Windows PE 4.0. You must create all hard disk partitions before you start this process, unless you run this command by using a script. If you use the /apply command for a directory structure, the command includes the specified directory, which includes all subdirectories and files. You must include the parent directory for the /apply command. Otherwise, when the image is applied, it overwrites everything in that location. For example, if you apply the image to drive C, the /apply command overwrites everything on drive C with your image files. To automate creating a directory, you must add the mkdir<target_directory> command to your script before executing imagex /apply. <image_file> The name and location of the volume image applied to the directory. <image_number> The number that references the specific volume in the .wim file. <image_name> The name that identifies the image in the .wim file. <image_path> The file path where the image will be applied. The following code example shows how to use the /applies option. imagex /apply d:\imaging\data.wim 1 d:\New_Directory /verify
/capture	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. To capture a directory, it must contain at least one file. ImageX does not support extended attributes and ignores them during a capture session. During the capture operation, fast compression is automatically applied. If you must have a different compression type, use the /compress option. <image_path> The name and location of the volume image for capture. <image_file> The name and location of the new .wim file. <"name"> The name of the new .wim file. This value is required. The straight quotation marks are required. <"description"> The text that provides additional reference information. The value is optional. The straight quotation marks are required. The following code example shows how to use the /capture option. imagex /capture d: d:\imaging\data.wim "Drive D" /verifyimagex /capture c: d:\install.wim "MyImage" /compress fast /check /scroll
/delete	Deletes the specified volume image from a .wim file that has multiple volume images. This command deletes only the metadata entries and XML entries, it does not delete the stream data and does not optimize the .wim file. You must run this command from Windows PE 4.0. 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. As soon as the file is mounted, you can view, but not modify, all the information that is contained in the directory. If you do not specify the parameters to mount, this command lists all mounted images. <image_file> The name and location of the .wim file specified for deletion. <image_number> The number that references the specific image in the .wim file to be deleted. <image_name> The name that references the image in the .wim file to be deleted. The following code example shows how to use the /delete option. imagex /delete d:\imaging\data.wim 1
/dir	Displays a list of the files and folders in a specified volume image. <image_file> The name and location of the volume image for review. If you do not provide a volume image, this command returns a directory listing for all volume images in the .wim file. <image_number> The number that references the specific volume in the .wim file. <image_name> The name that identifies an image in the .wim file. The following code example shows how to use the /dir option. imagex /dir d:\imaging\data.wim 1
/export	Exports a copy of the specified .wim file to another .wim file. The source and destination files must use the same compression type. Caution: You must run this command from Windows PE 4.0. Additionally, you must make sure you have sufficient disk space for the /export command to complete. If you run out of disk space while the /export command runs, the .wim file specified by <dest_file> may be corrupted. <src_file> The file path of the .wim file that contains the image to be exported. <src_number> The number that references the specific volume in the .wim file. <src_name> The name that identifies the image in the source .wim file. <dest_file> The file path of the .wim file that will receive the image copy. <dest_name> The unique name for the image in the destination .wim file. The following code example shows how to use the /export option. imagex /export d:\imaging\data.wim d:\imaging\sample.wim 1
/info	Returns the stored XML description for the specified .wim file. This description includes, but is not limited to, the total file size, the image index number, the directory count, file count, and a description. <image_file> The name and location of the .wim file for XML data review. <image_number> The number that identifies an image in the .wim file. <image_name> The name that identifies an image in the .wim file. <new_name> The new unique name for the specified image. <new_desc> The new description for the specified image. The following code example shows how to use the /info option. imagex /info d:\imaging\data.wim
/split	Splits an existing .wim file into multiple read-only split .wim files (.swm). You must run this command from Windows PE 4.0. <image_file> The name and location of the .wim file to split. <dest_file> The file path of the split files. <size> The maximum size in megabytes (MB) for each created file. This option generates the .swm files in 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 that is named Data.wim, this option creates a Data.swm file, a Data2.swm file, a Data3.swm file, and so on, defining each part of the split .wim file. The following code example shows how to use the /split option. imagex /split d:\imaging\data.wim 600
/mount	Mounts a .wim file from Windows XP Service Pack 2 (Windows XP SP2), Windows Server 2003 Service Pack 1 (Windows Server 2003 SP1), Windows 7, or Standard 8 with read-only permission to a specified directory. As soon as the file is mounted, you may view, but not modify, all the information that is contained in the directory. Note: You must install the WIM FS filter before you can mount an image. <image_file> The name and location of the .wim file that contains the specified image. <image_number> The number that identifies an image in the .wim file. <image_name> The name that identifies an image in the .wim file. <image_path> The file path where the specified image will be mounted. The following code example shows how to use the /mount option. imagex /mount d:\imaging\data.wim 2 c:\mounted_images
/mountrw	Mounts a .wim file from Windows XP Service Pack 2 (Windows XP SP2), Windows Server 2003 Service Pack 1 (Windows Server 2003 SP1), Windows 7, or Standard 8 with read/write permissions to a specified directory. As soon as the file is mounted, you may view and modify all the information that is contained in the directory. Note: You must install the WIM FS filter before you can mount an image. The /mountrw command requires exclusive access to the .wim file. Therefore, you cannot use the /mountrw command if an image in the .wim file is currently mounted by using the /mount command or the /mountrw command. Important: You must not mount an image to the parent or 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 command. Additionally, you must not mount your image to Standard 8 reserved folders. <image_file> The name and location of the .wim file to mount with read/write permission. <image_number> The number that identifies an image in the .wim file. <image_name> The name that identifies an image in the .wim file. <image_path> The file path where the specified image will be mounted. The following code example shows how to use the /mountrw option. imagex /mountrw d:\imaging\data.wim 2 c:\mounted_images
/remount	Recovers an orphaned mount path. This command is not supported from a rebooted Windows PE 4.0 environment. <image_path> The file path to an image that should be remounted. If you do not supply a path, the /remount command lists mounted images. The following code example shows how to use the /remount option. imagex /remount c:\mounted_images
/commit	Commits the changes made to a mounted image without also unmounting the image. <mount_path> The path of the mounted image to commit. <"image_name"> The name that identifies an image in the .wim file. Required if the /append option is used. [/append] Commits the changes as part of a new image in the .wim file. The following code example shows how to use the /commit option. imagex /commit c:\mounted_images
/unmount	Unmounts the mounted image from a specified directory. <image_path> The complete path to the location where an image was mounted. If you do not specify a directory, this option lists all mounted images. [/commit] Commits your changes to the .wim file before the image is unmounted. If you use the /unmount command without the /commit option, your changes are discarded. To be able to save your changes, you must mount the image using the /mountrw command and use the /commit option when unmounting the image. Caution: Confirm that you have sufficient hard disk space before using the /unmount command with the /commit option. You must account for the size of the files that you add to the .wim file, plus any increase in file size because of the modification of existing files, minus any files that you deleted, before you use the /unmount command with this option. If you have insufficient hard disk space to support an increase in size for the .wim file, an error occurs. The following code example shows how to use the /unmounts option. imagex /unmount /commit c:\mounted_images
/cleanup	Deletes all the resources associated with a mounted image that has been abandoned. Note: This command will not unmount currently mounted images, nor will it delete images that can be recovered via the /remount command. The following code example shows how to use the /cleanup option. imagex /cleanup
/boot	Marks a volume image as bootable. This option applies only to Windows PE 4.0 images. Only one volume image can be marked as bootable in a .wim file.
/check	Checks the integrity of the .wim file. If you do not use this option, 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 using maximum. Fast is also the default compression type if the parameter is left blank. The none option does not compress the captured image at all. Although the compression type you choose affects the capture time, it only slightly affects the apply time.
/config	The name and location of the configuration file. You can rename this file as necessary.
/norpfix	Disables the reparse point tag fix-up. A reparse point is a file that contains a link to another file on the file system. If not provided, reparse points that resolve to paths outside of the <image_path> are not captured.
/optimize	Reduces initial mount time.
/ref<split_wim_file.swm>	Enables the reference of split .wim files. <split_wim_file.swm> is the name and location of additional split files. Wildcard characters are accepted.
/temp	Specifies the path where temporary files are stored.
/verify	Enables file resource verification by checking for errors and file duplication.
/xml	Returns the output as well-formed XML.

/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 that was generated during a capture operation.

The /check option is designed to detect the 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 options will affect performance during the apply operations. We 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 Note: ImageX is an interface for Windows Imaging API
3	Invalid configuration script
4	Access denied, requires administrator privileges

See Also

Other Resources

Tools Technical Reference