WIMAPPLY(1)

wimapply(1) — User Commands

ok so before we even get into it: this is the part 1 of the page, bestie, there's more coming, don't go anywhere 🫶

✨ NAME ✨

• wimapply — apply a WIM image 💅

---

🌸 SYNOPSIS 🌸

wimapply WIMFILE [IMAGE] TARGET [OPTION...]

---

💖 DESCRIPTION 💖

okay so wimapply — and yes, wimlib-imagex apply does literally the exact same thing, they're twins, no cap — extracts (the cool kids say "applies") an image, or all the images, out of the Windows Imaging (WIM) archive you point at with WIMFILE. ✨

IMAGE is like, which image inside WIMFILE you want out. It can be:

• the 1-based index of an image (so the first one is 1, not 0, okay? we're not doing that zero-index thing here)
• the name of an image
• the keyword all if you want every single image, all of them, the whole collection 💅

You can straight up leave IMAGE out if WIMFILE only has one image in it — it's giving "obviously there's only one, girl". And if you ever need to see what's actually in there, run wiminfo(1) and it'll list all the images for you 🎀

TARGET is where it all goes. If TARGET is a directory, the image(s) get extracted into it following DIRECTORY EXTRACTION (UNIX) or DIRECTORY EXTRACTION (WINDOWS). And if TARGET doesn't even exist yet? No stress, a directory gets created there first, main character energy, it builds its own stage 🌟

Alternatively — and this is the spicy one — if TARGET is a UNIX block device, then the image gets extracted onto it as described in NTFS VOLUME EXTRACTION (UNIX). 🔥

Heads up bestie: wimapply is built to extract, aka "apply", full WIM images. If you only want some files or directories out of a WIM image, you want wimextract(1) instead. Different tool, different vibe.

If IMAGE is all, then every image in WIMFILE gets extracted into subdirectories of TARGET named after the images — and if an image has no name or an unusual name, it falls back to the image index instead. Not gonna lie, this is not yet supported in NTFS VOLUME EXTRACTION (UNIX) mode. 🙈

And if WIMFILE is -, then the WIM is read from standard input instead of from disk. Peep PIPABLE WIMS below for the full tea. 🧚

---

🦋 DIRECTORY EXTRACTION (UNIX) 🦋

On UNIX-like systems, a WIM image can be extracted to a directory. Cute, right? Except — and I need you to hear me — this mode has a limitation: NTFS or Windows-specific metadata will not be extracted. 😭

Some concepts do get translated to their UNIX equivalents:

• hard links
• symbolic links
• last access timestamps
• last modification timestamps

but everything else? lost, girl, with warnings given so at least you know. 💀

Notably, these types of metadata will not be extracted in this mode:

• Windows file attribute flags
• Windows security descriptors (e.g. file owners and DACLs)
• File creation timestamps
• Reparse points other than symbolic links and junction points
• Named data streams
• Short filenames (also known as 8.3 names or DOS names).
• Object IDs

Same exact limitations apply to wimextract, so it's not just a wimapply thing, it's a this-mode thing. As such, this mode is most useful when NTFS or Windows-specific metadata is unimportant — like when you're extracting specific files, or when you're doing file archiving only on UNIX-like systems, possibly in combination with --unix-data. 🌸

When Windows-specific metadata does matter to you? Then either use the NTFS VOLUME EXTRACTION (UNIX) mode, or use the Windows version of wimlib (see DIRECTORY EXTRACTION (WINDOWS)). Pick your fighter. 💅

---

👑 NTFS VOLUME EXTRACTION (UNIX) 👑

On UNIX-like systems, TARGET can also be a block device (e.g. /dev/sda3) holding an unmounted NTFS volume. In this mode, wimapply uses libntfs-3g to apply the specified WIM image to the root directory of the NTFS volume. The target volume should be empty, like freshly created by mkntfs(8) — a blank canvas, an empty page, we love to see it. ✨

In this mode, NTFS-specific and Windows-specific data and metadata will be extracted, including:

• All data streams of all files except encrypted files, including the unnamed data stream as well as all named data streams.
• Reparse points, including symbolic links, junction points, and other reparse points.
• File and directory creation, access, and modification timestamps, using the native NTFS resolution of 100 nanoseconds.
• Windows security descriptors, including all components (owner, group, DACL, and SACL).
• Windows file attribute flags
• All names of all files, including names in the Win32 namespace, DOS namespace, Win32+DOS namespace, and POSIX namespace. This includes hard links.
• Object IDs.

However — and I'm sorry to report this — encrypted files will not be extracted. 😭

Restoring extended attributes (EAs) is also not yet supported in this mode. One day. Maybe. Not today.

Regardless, since almost all information from the WIM image is restored in this mode, it is possible (and fully supported, periodt) to restore an image of an actual Windows installation using wimapply on a UNIX-like system as an alternative to using wimapply or DISM on Windows. In the EXAMPLES section below, there's an example of applying an image from an "install.wim" file as may be found in the Windows installation media. 🎀

Now, real talk: to actually boot Windows (Vista or later) from an applied "install.wim" image, you also need to mark the partition as "bootable" and set up various boot files, such as \BOOTMGR and \BOOT\BCD. The latter task is most easily accomplished by running bcdboot.exe from a live Windows system such as Windows PE, but there are other options as well. iykyk 🫶

Finally — and this one trips people up — note that this mode uses libntfs-3g directly, without going through the ntfs-3g(8) driver. So there is no special support for applying a WIM image to a directory on which an NTFS filesystem has been mounted using ntfs-3g(8) — you have to unmount it first, bestie, no shortcuts. There's also no support for applying a WIM image to some subdirectory of the NTFS volume; you can only apply to the root directory. That's the rule. 💅

---

🌈 DIRECTORY EXTRACTION (WINDOWS) 🌈

On Windows, wimapply (and wimextract) natively support NTFS and Windows-specific metadata. Iconic behaviour, honestly.

For best results, the target directory should be located on an NTFS volume and the program should be run with Administrator privileges. That said — non-NTFS filesystems and running without Administrator privileges are also supported, subject to limitations. So you're not locked out, you're just on hard mode. 😌

On Windows, wimapply tries to extract as much data and metadata as possible, including:

• All data streams of all files. This includes the default file contents, as well as named data streams if supported by the target volume.
• Reparse points, including symbolic links, junction points, and other reparse points, if supported by the target volume. Restoring symlinks requires Administrator privileges. Also see --rpfix and --norpfix for details on how absolute symbolic links and junctions are extracted.
• File and directory creation, access, and modification timestamps, to the highest resolution supported by the target volume.
• Security descriptors, if supported by the filesystem and --no-acls is not specified. Note that this, in general, requires Administrator privileges, and may be only partially successful if the program is run without Administrator privileges (see --strict-acls).
• File attribute flags, including hidden, compressed, encrypted, sparse, etc, when supported by the filesystem.
• Short filenames (also known as 8.3 names or DOS names).
• Hard links, if supported by the target filesystem.
• Object IDs, if supported by the target filesystem.
• Extended attributes (EAs), if supported by the target filesystem.

Additional notes about extracting files on Windows — because there's always a "but":

• wimapply will issue warnings if unable to extract the exact metadata and data of the WIM image due to limitations of the target filesystem.
• Since encrypted files (with FILE_ATTRIBUTE_ENCRYPTED) are not stored in plaintext in the WIM image, wimapply cannot restore encrypted files to filesystems not supporting encryption. Therefore, on such filesystems, encrypted files will not be extracted. Furthermore, even if encrypted files are restored to a filesystem that supports encryption, they will only be decryptable if the decryption key is available. No key, no vibes, no files. 🔑
• Files with names that cannot be represented on Windows will not be extracted by default; see --include-invalid-names.
• Files with full paths over 260 characters (the so-called MAX_PATH) will be extracted, but beware that such files will be inaccessible to most Windows software and may not be able to be deleted easily. They're giving cursed artifact, honestly. 💀
• On Windows, unless the --no-acls option is specified, wimlib will attempt to restore files' security descriptors exactly as they are provided in the WIM image. Beware that typical Windows installations contain files whose security descriptors do not allow the Administrator to delete them. Therefore, such files will not be able to be deleted, or in some cases even read, after extracting, unless processed with a specialized program that knows to acquire the SE_RESTORE_NAME and/or SE_BACKUP_NAME privileges which allow overriding access control lists. This is not a bug in wimlib — it works as designed to correctly restore the data that was archived — it's rather a problem with the access rights Windows uses on certain files. But if you just want the file data and don't care about security descriptors, use --no-acls to skip restoring all security descriptors. Slay, problem solved. 💅
• A similar caveat to the above applies to file attributes such as Readonly, Hidden, and System. By design, on Windows wimlib will restore such file attributes; therefore, extracted files may have those attributes. If this is not what you want, use the --no-attributes option. ✨

---

🎀 SPLIT WIMS 🎀

You may use wimapply to apply images from a split WIM, or wimextract to extract files from a split WIM. The WIMFILE argument must specify the first part of the split WIM, while the additional parts of the split WIM must be specified in one or more --ref="GLOB" options. Since globbing is built right into the --ref option, typically only one --ref option is necessary. Efficiency, we love her. 🌸

For example, the names for the split WIM parts usually go something like:

mywim.swm
mywim2.swm
mywim3.swm
mywim4.swm
mywim5.swm

To apply the first image of this split WIM to the directory "dir", run:

wimapply mywim.swm 1 dir --ref="mywim*.swm"

---

🧚 PIPABLE WIMS 🧚

wimapply also supports applying a WIM from a nonseekable file, such as a pipe — provided that the WIM was captured in the wimlib-specific pipable format using --pipable (see wimcapture(1)). To use standard input as the WIM, specify "-" as WIMFILE. A possible use of this feature is to apply a WIM image being streamed from the network. Streaming. From the network. Main character energy, no notes. 🌟

For example, to apply the first image from a WIM file available on a HTTP server to an NTFS volume on /dev/sda1, run something like:

wget -O - https://myserver/mywim.wim | wimapply - 1 /dev/sda1

Pipable WIMs may also be split into multiple parts, just like normal WIMs. To apply a split pipable WIM from a pipe, the parts must be concatenated and all written to the pipe. The first part must be sent first, but the remaining parts may be sent in any order. Yes, any order. Freedom. 🦋

---

✨ OPTIONS ✨

okay bestie this is the part where you get to customize your experience 💅 every flag is here, no skips, no crumbs.

• --check — before you apply the image, it goes and verifies the integrity of WIMFILE, but only if that file actually has extra integrity information. like a little pre-flight vibe check 🦋
• --ref="GLOB" — a file glob of additional WIMs or split WIM parts you want to pull resources from. see SPLIT_WIMS for the tea. you can drop this option multiple times if you're feeling extra. note: GLOB is in quotes because it's interpreted by wimapply itself, so you might need to quote it to protect it from shell expansion, iykyk 🐚
• --rpfix, --norpfix — sets whether to fix targets of absolute symbolic links (called "reparse points" in Windows land) or not. when it's enabled (--rpfix), extracted absolute symbolic links that the WIM image marks as "fixed" get assumed to have absolute targets relative to the image root — so wimapply prepends the absolute path of the extraction target directory to their targets. the whole point? you can apply an image full of absolute symbolic links and they'll still be valid no matter where you applied it. main character energy ✨

the default is --rpfix if any images in WIMFILE were captured with reparse-point fixups done. otherwise it's --norpfix.

heads up: reparse point fixups are never done in the NTFS volume extraction mode on UNIX-like systems. periodt.

• --unix-data — (UNIX-like systems only 🐧) restores UNIX-specific metadata and special files that got captured by wimcapture when it was run with the --unix-data option. that includes: standard UNIX file permissions (owner, group, and mode); device nodes, named pipes, and sockets; and extended attributes (Linux-only).
• --no-acls — do not restore security descriptors on extracted files and directories. simple as that 💖
• --strict-acls — fail immediately if the full security descriptor of any file or directory can't be set exactly as specified in the WIM file. if you don't pass this option, then when wimapply on Windows doesn't have permission to set a security descriptor on an extracted file, it falls back to setting it only partially (e.g. with SACL omitted), and in the worst case omits it entirely. that said, this should only be a problem if you're running wimapply without Administrator rights 🙈 also, on UNIX-like systems, this flag can be combined with --unix-data to make wimapply throw an error if UNIX permissions can't be applied to an extracted file.
• --no-attributes — do not restore Windows file attributes like readonly, hidden, etc. 🚫
• --include-invalid-names — extract files and directories with invalid names by replacing characters and appending a suffix, instead of just ignoring them. exactly what counts as "invalid" is platform-dependent, so let's break it down:

on POSIX-compliant systems, filenames are case-sensitive and may contain any byte except '\0' and /, so on a POSIX-compliant system this option will only have an effect in the unlikely case that the WIM image for some reason has a filename containing one of those characters. 🫠

on Windows, filenames are case-insensitive(*), cannot include control characters, and cannot include the characters /, '\0', \, :, *, ?, ", <, >, or |. ordinarily, files in WIM images should meet these conditions too. however, it is not guaranteed, and in particular a WIM image captured with wimcapture on a POSIX-compliant system could contain such files. by default, invalid names get ignored, and if there are multiple names differing only in case, one gets chosen to extract arbitrarily; but with --include-invalid-names, all names get sanitized and extracted in some form. slay 💅

(*) unless the ObCaseInsensitive setting has been set to 0 in the Windows registry, in which case certain software — including the Windows version of wimapply — will honor case-sensitive filenames on NTFS and other compatible filesystems. the more you know ⭐

• --wimboot — Windows only: instead of extracting the files themselves, it extracts "pointer files" that point back to the WIM archive(s). this can save a significant amount of space. but bestie, it comes at several potential costs, like not being able to delete the WIM archive(s) and possibly having slower access to files. see Microsoft's documentation for "WIMBoot" for more info.

if it exists, the [PrepopulateList] section of the file \Windows\System32\WimBootCompress.ini inside the WIM image gets read. files matching any of those patterns get extracted normally, not as WIMBoot "pointer files". this is helpful for certain files that Windows needs to read early in the boot process.

this option only works when the program is run as an Administrator and the target volume is NTFS or another filesystem that supports reparse points.

also, this option works best when running on Windows 8.1 Update 1 or later, since that's the first version of Windows that contains the Windows Overlay Filesystem filter driver ("WOF"). if the WOF driver is detected, wimlib will create the WIMBoot "pointer files" using documented ioctls provided by WOF. 🔥

otherwise, if the WOF driver is not detected, wimlib will create the reparse points and edit the file \System Volume Information\WimOverlay.dat on the target volume manually. this is potentially subject to problems, since although the code works in certain tested cases, neither of these data formats is actually documented by Microsoft 💀 before overwriting that file, wimlib will save the previous version in \System Volume Information\WimOverlay.wimlib_backup, which you potentially could restore if you needed to. good luck babe 🫶

you actually can still do a --wimboot extraction even if the WIM image isn't marked as "WIMBoot-compatible". this option causes the extracted files to be set as "externally backed" by the WIM file. Microsoft's driver that implements this "external backing" functionality seemingly does not care whether the image(s) in the WIM are really marked as WIMBoot-compatible. therefore, the "WIMBoot-compatible" tag (<WIMBOOT> in the XML data) seems to be a marker for intent only. in addition, the Microsoft driver can externally back files from WIM files that use XPRESS chunks of size 8192, 16384, and 32768, or LZX chunks of size 32768, in addition to the default XPRESS chunks of size 4096 that get created when wimcapture is run with the --wimboot option. the way that's SO specific 😭

• --compact=FORMAT — Windows-only: compress the extracted files using System Compression, when possible. this only works on either Windows 10 or later, or on an older Windows that's had Microsoft's wofadk.sys driver added to it. several different compression formats may be used with System Compression, and you must specify one as FORMAT. your choices are: xpress4k, xpress8k, xpress16k, and lzx. ✨

exclusions are handled the same way as with the --wimboot option. that is: if it exists, the [PrepopulateList] section of the file \Windows\System32\WimBootCompress.ini in the WIM image gets read, and files matching any of the patterns in this section will not be compressed. in addition, wimlib has a hardcoded list of files for which it knows — for compatibility with the Windows bootloader — to override the requested compression format. 👑

• --recover-data — if a file is corrupted (its stored hash doesn't match its actual hash, or some parts of it can't be decompressed), extract the corrupted file anyway with a warning, rather than aborting with an error. this may be useful to recover data if a WIM archive got corrupted. note that recovering data is not guaranteed to succeed, as it depends on the type of corruption that occurred. no promises bestie 🙈

---

🌸 NOTES 🌸

Data integrity: WIM files include checksums of file data. to detect accidental (non-malicious) data corruption, wimlib calculates the checksum of every file it extracts and issues an error if it doesn't have the expected value — unless the --recover-data option is given. (this default behavior seems equivalent to the /verify option of ImageX.) in addition, a WIM file can include an integrity table (extra checksums) over the raw data of the entire WIM file. for performance reasons wimlib does not check the integrity table by default, but the --check option can be passed to make it do so. 🦋

ESD files: wimlib can extract files from solid-compressed WIMs, or "ESD" (.esd) files, just like from normal WIM (.wim) files. however, Microsoft sometimes distributes ESD files with encrypted segments; wimlib cannot extract such files until they're first decrypted. 💀

Security: wimlib has been carefully written to validate all input and is believed to be secure against some types of attacks that often plague other file archiving programs — e.g. directory traversal attacks (which, as it happens, Microsoft's WIM software is vulnerable to 😭). important parts of wimlib, e.g. the decompressors, have also been fuzz tested. however, wimlib is not currently designed to protect against some types of denial-of-service (DOS) attacks, e.g. memory exhaustion or "zip bombs". stay safe out there 🫶

---

💖 EXAMPLES 💖

extract the first image from the Windows PE WIM on the Windows installation media to the directory boot:

wimapply /mnt/windows/sources/boot.wim 1 boot

on Windows, apply an image of an entire volume, for example from install.wim which can be found on the Windows installation media:

wimapply install.wim 1 E:\

same as above, but running on a UNIX-like system where the corresponding partition is /dev/sda2:

wimapply install.wim 1 /dev/sda2

note that before running either of the above commands, an NTFS filesystem may need to be created on the partition, for example with format.exe on Windows or mkntfs(8) on UNIX-like systems. for example, on UNIX you might run:

mkntfs /dev/sda2 && wimapply install.wim 1 /dev/sda2

(of course don't do that if you don't want to destroy all existing data on the partition!) 🚨 like fr fr that's not a drill

see SPLIT WIMS and PIPABLE WIMS for examples of applying split and pipable WIMs, respectively. 🌈

---

👑 SEE ALSO 👑

wimlib-imagex(1) wimcapture(1) wimextract(1) wiminfo(1)

---

aaaand that's a wrap on the whole page bestie, you ate that 💅 this was wimlib 1.14.5, dated January 2026, and the page is WIMAPPLY(1) — go forth and apply those images, you absolute icon 🎀✨💖