WIMUPDATE(1)

👑 WIMUPDATE — the manual page but make it cute

okay so bestie, welcome to wimupdate, from the User Commands section, aka WIMUPDATE(1). it's the whole vibe of "i want to change a WIM image and i want to do it from the command line." let's get into it 💅

---

✨ NAME ✨

wimupdate — Update a WIM image

---

🌸 SYNOPSIS 🌸

wimupdate WIMFILE [IMAGE] [OPTION...] [< CMDFILE]

---

🦋 DESCRIPTION 🦋

so wimupdate, or literally the exact same thing as wimlib-imagex update, modifies the specified IMAGE in the Windows Imaging (WIM) archive WIMFILE by adding, deleting, or renaming files or directories in it. that's the whole job. she does one thing and she does it well. 👑

IMAGE is like, which image inside WIMFILE you want to update. it can be either:

• the 1-based index of an image, or
• the name of an image.

and you can straight up skip it if WIMFILE only has one image in it (one-image WIMs stay winning). if you need to see what images are even in there, run wiminfo(1) and she'll list them for you. 🎀

now here's the main character part: the modifications you want to perform are specified as a sequence of commands, one per line, read from standard input as a text file. that file can be UTF-8 or UTF-16LE encoded, and plain ASCII is also fine btw, no stress.

💡 bestie please redirect standard input from a file (CMDFILE) like the synopsis shows, instead of typing commands in interactively. i'm begging. it's so much nicer.

oh and if you want to just specify one single command directly on the command line instead, go look at the --command option. iykyk. ✨

---

🎀 AVAILABLE COMMANDS 🎀

this section is all about the commands that can show up in the CMDFILE we were just talking about. let's go one by one, no skipping. 🌈

🍓 add [OPTION...] SOURCE DESTINATION

add a file or a whole directory tree to the WIM image. the deets:

• SOURCE has to be the path to a file or directory on your own filesystem.
• DESTINATION has to be the path inside the WIM image where you want that file or directory tree to land.

now, the branching logic, and yes it matters:

• if DESTINATION names an existing directory in the WIM image, then SOURCE must also name a directory. this makes the contents of the SOURCE directory get added into the DESTINATION directory. (contents, not the dir itself. important.)
• if DESTINATION names an existing nondirectory file in the WIM image, then SOURCE must also name a nondirectory file. by default this causes the DESTINATION file to be replaced with the SOURCE file. or, if you pass --no-replace, it generates an error instead. your call bestie.
• if DESTINATION doesn't exist in the WIM image at all, then any prerequisite directories are created as needed to put SOURCE at that location. she builds the road as she drives. 🛣️

the add command supports a subset of the options that wimcapture accepts, namely: --dereference, --unix-data, --no-acls, and --strict-acls. see wimcapture(1) for what those actually do.

on top of that, add also supports the --no-replace option, which makes add refuse to overwrite existing nondirectory files in the WIM image. so polite of her. 💅

🧚 delete [OPTION...] PATH

delete a file or directory tree from the WIM image. PATH must specify the path inside the WIM image of the file or directory tree you want gone. bye bye 🫶

the available options for the delete command are:

• --force — do not issue an error if the path to delete does not exist. (like, if it's already gone, whatever, we move on.)
• --recursive — delete the file or directory tree recursively. if you don't specify this, an error is issued if the path to delete is a directory. she's not gonna nuke a whole tree without your explicit consent, and honestly? respect.

💜 rename OLD_PATH NEW_PATH

rename a file or directory tree inside the WIM image.

• OLD_PATH = the old path of the file or directory tree inside the WIM image.
• NEW_PATH = the new path for that file or directory tree.

this command follows the semantics of the POSIX rename (3) function. in particular, a pre-existing file at NEW_PATH will be deleted if present — except in certain cases, like attempting to rename a directory to a non-directory, which is not allowed. so watch out for that one. 💀

and: there are no options available for the rename command. she's a no-frills icon. periodt.

---

💖 OPTIONS 💖

these are the options wimupdate itself accepts on the command line. sit down, there's a bunch, and we're doing all of them. ☕

• --dereference — use --dereference for all add commands.
• --unix-data — use --unix-data for all add commands.
• --no-acls — use --no-acls for all add commands.
• --strict-acls — use --strict-acls for all add commands.
• --no-replace — use --no-replace for all add commands.
• --config=FILE — set the capture configuration file for all add commands. see the description of this option in wimcapture(1).
• --force — use --force for all delete commands.
• --recursive — use --recursive for all delete commands.
• --check — before updating the WIM, verify its integrity if it contains extra integrity information. also, include extra integrity information in the updated WIM even if it wasn't there before. double duty. 💅
• --include-integrity — include extra integrity information in the updated WIM, i.e. like --check but don't also verify the WIM beforehand.
• --threads=NUM_THREADS — number of threads to use for compressing newly added files. default: autodetect (number of processors). let her cook on as many cores as she can find. 🔥
• --rebuild — rebuild the entire WIM rather than appending the updated data to the end of it. rebuilding the WIM is slower, but it will save a little bit of space that would otherwise be left as a hole in the WIM file.

also, see wimoptimize(1) for a more customizable way of rebuilding (and optionally recompressing) a WIM file. and heads up: if you're running wimoptimize after wimupdate, there is no need to specify --rebuild to wimupdate. don't do both, that's just doing it twice for no reason bestie.

• --command=STRING — instead of reading update commands from standard input, read a single update command directly from the string STRING specified on the command line.

rules of this one:

• this option cannot be provided more than one time
• and it cannot be used to specify more than one update command

note that the STRING, as well as any paths containing spaces within the STRING, must be appropriately quoted. if you're running from cmd.exe on Windows, you should use double quotes for the outer quotes and single quotes for the inner quotes. example:

wimupdate boot.wim 1 --command="add 'C:\My Dir' '\My Dir'"

🚨 this option is provided for convenience only. do NOT execute wimupdate multiple consecutive times, each time passing the --command option! that is inefficient. instead, generate an update command file and provide it (on standard input) to a single invocation of wimupdate, as explained in this document. one and done, like a queen. 👑

• --wimboot-config=FILE — if this option is specified, no commands shall be read from standard input, and instead the following command shall be executed:

add FILE /Windows/System32/WimBootCompress.ini

this sets FILE as the WIMBoot configuration file for the image. the [PrepopulateList] section of this file specifies path globs that shall not be extracted as WIMBoot pointer files (perhaps due to being needed early in the boot process). see the documentation for the --wimboot option of wimapply(1) for more information.

• --unsafe-compact — compact the WIM archive in-place and append any new data, eliminating "holes". this is efficient, but in general this option should not be used because a failed or interrupted compaction will corrupt the WIM archive. 😭 for more information, see the documentation for this option in wimoptimize(1).

⚠️ like, she literally has "unsafe" in the name. the name is not a vibe, it's a warning. you've been told. 💀

• --ref="GLOB" — file glob of WIM(s) on which the delta WIM is based. updating split WIMs is not allowed, but updating delta WIMs is allowed. when updating a delta WIM, the WIM(s) on which the delta WIM is based should be specified using this option. (it isn't a hard requirement, but it's needed for data deduplication to work fully and for the TOTALBYTES statistic to be correctly updated.)

---

🫶 NOTES 🫶

okay, the notes section, aka the "bestie pls read this part" part. 🎀

wimupdate can be viewed as redundant with wimmountrw, since a WIM image can also be updated by mounting it read-write. HOWEVER — and this is the slay — wimupdate works on all platforms including Windows, whereas wimmountrw only works on Linux. so if you're on Windows, she's the one. 💅

symbolic links inside a WIM image are not dereferenced when being interpreted. so, for example, if you have a WIM image that contains a symbolic link "/Documents and Settings" -> "/Users" where "/Users" is a directory, then a subdirectory named "Public" in this directory must be specified as "/Users/Public" rather than "/Documents and Settings/Public". yes, you have to spell it out the long way. she is not following the link for you. 🙈

all paths to files or directories within the WIM image must be specified relative to the root of the image. but, good news:

• the leading slash is optional
• and both forward slashes and backslashes are accepted — so / or \, she doesn't care, she's flexible like that

in addition:

• on Windows, paths are by default treated case-insensitively
• on UNIX-like systems, paths are by default treated case-sensitively

the default case sensitivity may be changed by setting the WIMLIB_IMAGEX_IGNORE_CASE environmental variable to 0 or 1. so you do have the switch, bestie. 🔘

the command file (CMDFILE) is parsed by wimupdate itself and not by the system shell. therefore, its syntax is limited. however:

• comment lines beginning with '#' are allowed
• and it is also possible to quote arguments with whitespace inside them

so it's limited but not that limited. she's got range. ✨

on UNIX-like systems, you cannot use wimupdate to add files to an image directly from an NTFS volume using libntfs-3g, even though wimcapture supports capturing a full image this way. yeah. that's just how it is. 😭

and finally, the safety note, listen up:

except when using --unsafe-compact, it is safe to abort a wimupdate command partway through. however, after doing this, it is recommended to run wimoptimize to remove any data that was appended to the physical WIM file but not yet incorporated into the structure of the WIM — unless --rebuild was specified, in which case you should delete the temporary file left over. 🌸

so like. aborting is fine. but clean up after yourself. we're not messy in this house. 💖

💫 EXAMPLES 💫

Okay bestie, every single example down here shows you both things at once: the update command file you're gonna create, and the wimupdate command you run to actually make those updates happen. Two-for-one, we love that for us. 🎀

---

🗑️ Deleting two files from a WIM image

update_commands.txt:

delete /setup.exe
delete /sources/setup.exe

Then run it:

$ wimupdate boot.wim 2 < update_commands.txt

---

📥 Adding some files and directories to a WIM image

Heads up bestie: the first path of each add command is the stuff you're adding, and the second path of each add command is where inside the WIM image it's gonna land. Two paths, two jobs, no confusion. ✨

update_commands.txt:

add somedir     /dir
add somefile    /dir/file

Then:

$ wimupdate boot.wim 2 < update_commands.txt

---

✏️ Renaming a file inside a WIM image

update_commands.txt:

rename /dir_in_wim/oldfile.txt /dir_in_wim/newfile.txt

Then:

$ wimupdate boot.wim 2 < update_commands.txt

---

👑 The glow-up example: comments, options, overlays, and extra integrity info

This one is the main character, fr fr. It uses additional features like comments, options, and overlays — and it even sneaks extra integrity information into the updated WIM. 💅

update_commands.txt:

#
# This file specifies some changes to make to a WIM image.
#

# Add a new directory containing files I want in the image.
# The quotes are necessary because the directory name
# contains a space.
add "My Directory" "/My Directory"

# Add the contents of "Another Directory" to the
# "/My Directory" we just created in the WIM image.  Since
# the destination path already exists, this performs an
# overlay.
add "Another Directory" "/My Directory"

# Rename some file for some reason.
rename /dir_in_wim/oldfile.txt /dir_in_wim/newfile.txt

# Delete an unwanted directory.
delete --recursive /Users/Me/Documents/Junk

And the run — peep the --check flag, she's doing the most (in a good way) 🫶:

$ wimupdate boot.wim 2 --check < update_commands.txt

---

🔍 SEE ALSO 🔍

wimlib-imagex(1) wimcapture(1) wiminfo(1) wimmountrw(1) wimoptimize(1)

---

That's the whole page, bestie!! 🦋 You made it to the end and I'm so proud of you. This beauty is from wimlib 1.14.5, dated January 2026, and she lives under the name WIMUPDATE(1). Go update some WIMs, you absolute icon. 💖✨🎀