1WIMAPPLY(1) User Commands WIMAPPLY(1)
2
6 wimapply - Apply a WIM image
7
9 wimapply WIMFILE [IMAGE] TARGET [OPTION...]
10
12 wimapply, or equivalently wimlib-imagex apply, extracts ("applies") an
13 image, or all images, from the Windows Imaging (WIM) archive WIMFILE.
14 IMAGE specifies the image in WIMFILE to extract. It may be the 1-based
16 index of an image, the name of an image, or the keyword "all" to spec‐
17 ify all images. It may be omitted if WIMFILE contains only one image.
18 You can use wiminfo(1) to list the images contained in WIMFILE.
19 TARGET specifies where to extract the image(s) to. If TARGET is a di‐
21 rectory, then the image(s) will be extracted to that directory as per
22 DIRECTORY EXTRACTION (UNIX) or DIRECTORY EXTRACTION (WINDOWS). If TAR‐
23 GET does not exist, then a directory will be created there first. Al‐
24 ternatively, if TARGET specifies a UNIX block device, then the image
25 will be extracted to it as described in NTFS VOLUME EXTRACTION (UNIX).
26 Note that wimapply is designed to extract, or "apply", full WIM images.
28 If you instead want to extract only certain files or directories from a
29 WIM image, use wimextract(1) instead.
30 If IMAGE is "all", then all images in WIMFILE will be extracted into
32 subdirectories of TARGET named after the images, falling back to the
33 image index when an image has no name or an unusual name. This is not
34 yet supported in NTFS VOLUME EXTRACTION (UNIX) mode.
35 If WIMFILE is "-", then the WIM is read from standard input rather than
37 from disk. See PIPABLE WIMS for more information.
38
40 On UNIX-like systems, a WIM image may be extracted to a directory.
41 This mode has the limitation that NTFS or Windows-specific metadata
42 will not be extracted. Although some concepts such as hard links, sym‐
43 bolic links, last access timestamps, and last modification timestamps
44 will be translated to their UNIX equivalents, other metadata will be
45 lost (with warnings given). Notably, the following types of metadata
46 will not be extracted in this mode:
47 • Windows file attribute flags
49 • Windows security descriptors (e.g. file owners and DACLs)
51 • File creation timestamps
53 • Reparse points other than symbolic links and junction points
55 • Named data streams
57 • Short filenames (also known as 8.3 names or DOS names).
59 • Object IDs
61 These same limitations apply to wimextract. As such, this mode is most
63 useful in situations where NTFS or Windows-specific metadata is unim‐
64 portant, e.g. when wanting to extract specific files, or when doing
65 file archiving only on UNIX-like systems, possibly in combination with
66 --unix-data. When Windows-specific metadata is important, then either
67 the NTFS VOLUME EXTRACTION (UNIX) mode should be used, or the Windows
68 version of wimlib should be used (see DIRECTORY EXTRACTION (WINDOWS)).
69
71 On UNIX-like systems, TARGET may also be specified as a block device
72 (e.g. /dev/sda3) containing an unmounted NTFS volume. In this mode,
73 wimapply uses libntfs-3g to apply the specified WIM image to the root
74 directory of the NTFS volume. The target volume should be empty, e.g.
75 newly created by mkntfs(8). In this mode, NTFS-specific and Windows-
76 specific data and metadata will be extracted, including the following:
77 • All data streams of all files except encrypted files, including the
79 unnamed data stream as well as all named data streams.
80 • Reparse points, including symbolic links, junction points, and
82 other reparse points.
83 • File and directory creation, access, and modification timestamps,
85 using the native NTFS resolution of 100 nanoseconds.
86 • Windows security descriptors, including all components (owner,
88 group, DACL, and SACL).
89 • Windows file attribute flags
91 • All names of all files, including names in the Win32 namespace, DOS
93 namespace, Win32+DOS namespace, and POSIX namespace. This includes
94 hard links.
95 • Object IDs.
97 However, encrypted files will not be extracted.
99 Restoring extended attributes (EAs) is also not yet supported in this
101 mode.
102 Regardless, since almost all information from the WIM image is restored
104 in this mode, it is possible (and fully supported) to restore an image
105 of an actual Windows installation using wimapply on a UNIX-like system
106 as an alternative to using wimapply or DISM on Windows. In the EXAM‐
107 PLES section below, there is an example of applying an image from an
108 "install.wim" file as may be found in the Windows installation media.
109 Note that to actually boot Windows (Vista or later) from an applied
111 "install.wim" image, you also need to mark the partition as "bootable"
112 and set up various boot files, such as \BOOTMGR and \BOOT\BCD. The
113 latter task is most easily accomplished by running bcdboot.exe from a
114 live Windows system such as Windows PE, but there are other options as
115 well.
116 Finally, note that this mode uses libntfs-3g directly, without going
118 through the ntfs-3g(8) driver. Hence, there is no special support for
119 applying a WIM image to a directory on which an NTFS filesystem has
120 been mounted using ntfs-3g(8); you have to unmount it first. There is
121 also no support for applying a WIM image to some subdirectory of the
122 NTFS volume; you can only apply to the root directory.
123
125 On Windows, wimapply (and wimextract) natively support NTFS and Win‐
126 dows-specific metadata. For best results, the target directory should
127 be located on an NTFS volume and the program should be run with Admin‐
128 istrator privileges; however, non-NTFS filesystems and running without
129 Administrator privileges are also supported, subject to limitations.
130 On Windows, wimapply tries to extract as much data and metadata as pos‐
132 sible, including:
133 • All data streams of all files. This includes the default file con‐
135 tents, as well as named data streams if supported by the target
136 volume.
137 • Reparse points, including symbolic links, junction points, and
139 other reparse points, if supported by the target volume. Restoring
140 symlinks requires Administrator privileges. Also see --rpfix and
141 --norpfix for details on how absolute symbolic links and junctions
142 are extracted.
143 • File and directory creation, access, and modification timestamps,
145 to the highest resolution supported by the target volume.
146 • Security descriptors, if supported by the filesystem and --no-acls
148 is not specified. Note that this, in general, requires Administra‐
149 tor privileges, and may be only partially successful if the program
150 is run without Administrator privileges (see --strict-acls).
151 • File attribute flags, including hidden, compressed, encrypted,
153 sparse, etc, when supported by the filesystem.
154 • Short filenames (also known as 8.3 names or DOS names).
156 • Hard links, if supported by the target filesystem.
158 • Object IDs, if supported by the target filesystem.
160 • Extended attributes (EAs), if supported by the target filesystem.
162 Additional notes about extracting files on Windows:
164 • wimapply will issue warnings if unable to extract the exact meta‐
166 data and data of the WIM image due to limitations of the target
167 filesystem.
168 • Since encrypted files (with FILE_ATTRIBUTE_ENCRYPTED) are not
170 stored in plaintext in the WIM image, wimapply cannot restore en‐
171 crypted files to filesystems not supporting encryption. Therefore,
172 on such filesystems, encrypted files will not be extracted. Fur‐
173 thermore, even if encrypted files are restored to a filesystem that
174 supports encryption, they will only be decryptable if the decryp‐
175 tion key is available.
176 • Files with names that cannot be represented on Windows will not be
178 extracted by default; see --include-invalid-names.
179 • Files with full paths over 260 characters (the so-called MAX_PATH)
181 will be extracted, but beware that such files will be inaccessible
182 to most Windows software and may not be able to be deleted easily.
183 • On Windows, unless the --no-acls option is specified, wimlib will
185 attempt to restore files' security descriptors exactly as they are
186 provided in the WIM image. Beware that typical Windows installa‐
187 tions contain files whose security descriptors do not allow the Ad‐
188 ministrator to delete them. Therefore, such files will not be able
189 to be deleted, or in some cases even read, after extracting, unless
190 processed with a specialized program that knows to acquire the
191 SE_RESTORE_NAME and/or SE_BACKUP_NAME privileges which allow over‐
192 riding access control lists. This is not a bug in wimlib, which
193 works as designed to correctly restore the data that was archived,
194 but rather a problem with the access rights Windows uses on certain
195 files. But if you just want the file data and don't care about se‐
196 curity descriptors, use --no-acls to skip restoring all security
197 descriptors.
198 • A similar caveat to the above applies to file attributes such as
200 Readonly, Hidden, and System. By design, on Windows wimlib will
201 restore such file attributes; therefore, extracted files may have
202 those attributes. If this is not what you want, use the --no-at‐
203 tributes option.
204
206 You may use wimapply to apply images from a split WIM, or wimextract to
207 extract files from a split WIM. The WIMFILE argument must specify the
208 first part of the split WIM, while the additional parts of the split
209 WIM must be specified in one or more --ref="GLOB" options. Since glob‐
210 bing is built into the --ref option, typically only one --ref option is
211 necessary. For example, the names for the split WIM parts usually go
212 something like:
213 mywim.swm
215 mywim2.swm
216 mywim3.swm
217 mywim4.swm
218 mywim5.swm
219 To apply the first image of this split WIM to the directory "dir", run:
221 wimapply mywim.swm 1 dir --ref="mywim*.swm"
223
225 wimapply also supports applying a WIM from a nonseekable file, such as
226 a pipe, provided that the WIM was captured in the wimlib-specific pi‐
227 pable format using --pipable (see wimcapture(1)). To use standard in‐
228 put as the WIM, specify "-" as WIMFILE. A possible use of this feature
229 is to apply a WIM image being streamed from the network. For example,
230 to apply the first image from a WIM file available on a HTTP server to
231 an NTFS volume on /dev/sda1, run something like:
232 wget -O - https://myserver/mywim.wim | wimapply - 1 /dev/sda1
234 Pipable WIMs may also be split into multiple parts, just like normal
236 WIMs. To apply a split pipable WIM from a pipe, the parts must be con‐
237 catenated and all written to the pipe. The first part must be sent
238 first, but the remaining parts may be sent in any order.
239
241 --check
242 Before applying the image, verify the integrity of WIMFILE if it
243 has extra integrity information.
244 --ref="GLOB"
246 File glob of additional WIMs or split WIM parts to reference re‐
247 sources from. See SPLIT_WIMS. This option can be specified mul‐
248 tiple times. Note: GLOB is listed in quotes because it is inter‐
249 preted by wimapply and may need to be quoted to protect against
250 shell expansion.
251 --rpfix, --norpfix
253 Set whether to fix targets of absolute symbolic links (reparse
254 points in Windows terminology) or not. When enabled (--rpfix),
255 extracted absolute symbolic links that are marked in the WIM im‐
256 age as being fixed are assumed to have absolute targets relative
257 to the image root, and therefore wimapply prepends the absolute
258 path to the extraction target directory to their targets. The
259 intention is that you can apply an image containing absolute sym‐
260 bolic links and still have them be valid after it has been ap‐
261 plied to any location.
262 The default behavior is --rpfix if any images in WIMFILE have
264 been captured with reparse-point fixups done. Otherwise, it is
265 --norpfix.
266 Reparse point fixups are never done in the NTFS volume extraction
268 mode on UNIX-like systems.
269 --unix-data
271 (UNIX-like systems only) Restore UNIX-specific metadata and spe‐
272 cial files that were captured by wimcapture with the --unix-data
273 option. This includes: standard UNIX file permissions (owner,
274 group, and mode); device nodes, named pipes, and sockets; and ex‐
275 tended attributes (Linux-only).
276 --no-acls
278 Do not restore security descriptors on extracted files and direc‐
279 tories.
280 --strict-acls
282 Fail immediately if the full security descriptor of any file or
283 directory cannot be set exactly as specified in the WIM file. If
284 this option is not specified, when wimapply on Windows does not
285 have permission to set a security descriptor on an extracted
286 file, it falls back to setting it only partially (e.g. with SACL
287 omitted), and in the worst case omits it entirely. However, this
288 should only be a problem when running wimapply without Adminis‐
289 trator rights. Also, on UNIX-like systems, this flag can also be
290 combined with --unix-data to cause wimapply to issue an error if
291 UNIX permissions are unable to be applied to an extracted file.
292 --no-attributes
294 Do not restore Windows file attributes such as readonly, hidden,
295 etc.
296 --include-invalid-names
298 Extract files and directories with invalid names by replacing
299 characters and appending a suffix rather than ignoring them. Ex‐
300 actly what is considered an "invalid" name is platform-dependent.
301 On POSIX-compliant systems, filenames are case-sensitive and may
303 contain any byte except '\0' and ´/', so on a POSIX-compliant
304 system this option will only have an effect in the unlikely case
305 that the WIM image for some reason has a filename containing one
306 of these characters.
307 On Windows, filenames are case-insensitive(*), cannot include
309 control characters, and cannot include the characters '/', ´\0',
310 '\', ':', '*', '?', ´"', '<', '>', or '|'. Ordinarily, files in
311 WIM images should meet these conditions as well. However, it is
312 not guaranteed, and in particular a WIM image captured with wim‐
313 capture on a POSIX-compliant system could contain such files. By
314 default, invalid names will be ignored, and if there are multiple
315 names differing only in case, one will be chosen to extract arbi‐
316 trarily; however, with --include-invalid-names, all names will be
317 sanitized and extracted in some form.
318 (*) Unless the ObCaseInsensitive setting has been set to 0 in the
320 Windows registry, in which case certain software, including the
321 Windows version of wimapply, will honor case-sensitive filenames
322 on NTFS and other compatible filesystems.
323 --wimboot
325 Windows only: Instead of extracting the files themselves, extract
326 "pointer files" back to the WIM archive(s). This can result in
327 significant space savings. However, it comes at several poten‐
328 tial costs, such as not being able to delete the WIM archive(s)
329 and possibly having slower access to files. See Microsoft's doc‐
330 umentation for "WIMBoot" for more information.
331 If it exists, the [PrepopulateList] section of the file \Win‐
333 dows\System32\WimBootCompress.ini in the WIM image will be read.
334 Files matching any of these patterns will be extracted normally,
335 not as WIMBoot "pointer files". This is helpful for certain
336 files that Windows needs to read early in the boot process.
337 This option only works when the program is run as an Administra‐
339 tor and the target volume is NTFS or another filesystem that sup‐
340 ports reparse points.
341 In addition, this option works best when running on Windows 8.1
343 Update 1 or later, since that is the first version of Windows
344 that contains the Windows Overlay Filesystem filter driver
345 ("WOF"). If the WOF driver is detected, wimlib will create the
346 WIMBoot "pointer files" using documented ioctls provided by WOF.
347 Otherwise, if the WOF driver is not detected, wimlib will create
349 the reparse points and edit the file "\System Volume Informa‐
350 tion\WimOverlay.dat" on the target volume manually. This is po‐
351 tentially subject to problems, since although the code works in
352 certain tested cases, neither of these data formats is actually
353 documented by Microsoft. Before overwriting this file, wimlib
354 will save the previous version in "\System Volume Informa‐
355 tion\WimOverlay.wimlib_backup", which you potentially could re‐
356 store if you needed to.
357 You actually can still do a --wimboot extraction even if the WIM
359 image is not marked as "WIMBoot-compatible". This option causes
360 the extracted files to be set as "externally backed" by the WIM
361 file. Microsoft's driver which implements this "external back‐
362 ing" functionality seemingly does not care whether the image(s)
363 in the WIM are really marked as WIMBoot-compatible. Therefore,
364 the "WIMBoot-compatible" tag (<WIMBOOT> in the XML data) seems to
365 be a marker for intent only. In addition, the Microsoft driver
366 can externally back files from WIM files that use XPRESS chunks
367 of size 8192, 16384, and 32768, or LZX chunks of size 32768, in
368 addition to the default XPRESS chunks of size 4096 that are cre‐
369 ated when wimcapture is run with the --wimboot option.
370 --compact=FORMAT
372 Windows-only: compress the extracted files using System Compres‐
373 sion, when possible. This only works on either Windows 10 or
374 later, or on an older Windows to which Microsoft's wofadk.sys
375 driver has been added. Several different compression formats may
376 be used with System Compression, and one must be specified as
377 FORMAT. The choices are: xpress4k, xpress8k, xpress16k, and lzx.
378 Exclusions are handled in the same way as with the --wimboot op‐
380 tion. That is: if it exists, the [PrepopulateList] section of
381 the file \Windows\System32\WimBootCompress.ini in the WIM image
382 will be read, and files matching any of the patterns in this sec‐
383 tion will not be compressed. In addition, wimlib has a hardcoded
384 list of files for which it knows, for compatibility with the Win‐
385 dows bootloader, to override the requested compression format.
386 --recover-data
388 If a file is corrupted (its stored hash doesn't match its actual
389 hash, or some parts of it can't be decompressed), extract the
390 corrupted file anyway with a warning, rather than aborting with
391 an error. This may be useful to recover data if a WIM archive
392 was corrupted. Note that recovering data is not guaranteed to
393 succeed, as it depends on the type of corruption that occurred.
394
396 Data integrity: WIM files include checksums of file data. To detect
397 accidental (non-malicious) data corruption, wimlib calculates the
398 checksum of every file it extracts and issues an error if it does not
399 have the expected value, unless the --recover-data option is given.
400 (This default behavior seems equivalent to the /verify option of Im‐
401 ageX.) In addition, a WIM file can include an integrity table (extra
402 checksums) over the raw data of the entire WIM file. For performance
403 reasons wimlib does not check the integrity table by default, but the
404 --check option can be passed to make it do so.
405 ESD files: wimlib can extract files from solid-compressed WIMs, or
407 "ESD" (.esd) files, just like from normal WIM (.wim) files. However,
408 Microsoft sometimes distributes ESD files with encrypted segments; wim‐
409 lib cannot extract such files until they are first decrypted.
410 Security: wimlib has been carefully written to validate all input and
412 is believed to be secure against some types of attacks which often
413 plague other file archiving programs, e.g. directory traversal attacks
414 (which, as it happens, Microsoft's WIM software is vulnerable to). Im‐
415 portant parts of wimlib, e.g. the decompressors, have also been fuzz
416 tested. However, wimlib is not currently designed to protect against
417 some types of denial-of-service (DOS) attacks, e.g. memory exhaustion
418 or "zip bombs".
419
421 Extract the first image from the Windows PE WIM on the Windows instal‐
422 lation media to the directory "boot":
423 wimapply /mnt/windows/sources/boot.wim 1 boot
425 On Windows, apply an image of an entire volume, for example from "in‐
427 stall.wim" which can be found on the Windows installation media:
428 wimapply install.wim 1 E:\
430 Same as above, but running on a UNIX-like system where the correspond‐
432 ing partition is /dev/sda2:
433 wimapply install.wim 1 /dev/sda2
435 Note that before running either of the above commands, an NTFS filesys‐
437 tem may need to be created on the partition, for example with for‐
438 mat.exe on Windows or mkntfs(8) on UNIX-like systems. For example, on
439 UNIX you might run:
440 mkntfs /dev/sda2 && wimapply install.wim 1 /dev/sda2
442 (Of course don't do that if you don't want to destroy all existing data
444 on the partition!)
445 See SPLIT WIMS and PIPABLE WIMS for examples of applying split and pi‐
447 pable WIMs, respectively.
448
450 wimlib-imagex(1) wimcapture(1) wimextract(1) wiminfo(1)
451wimlib 1.14.3 September 2023 WIMAPPLY(1)