wimlib Documentation

Introduction

wimlib is a C library to read, write, and mount archive files in the Windows Imaging Format (WIM files). These files are normally created using the imagex.exe utility on Windows, but this library provides a free implementetion of imagex for UNIX-based systems and an API to allow other programs to read, write, and mount WIM files. wimlib is comparable to Microsoft's WIMGAPI, but was designed independently and is not a clone of it.

The main intended use of wimlib is to create customized images of Windows PE, the Windows Preinstallation Environment, without having to rely on Windows. Windows PE, which is the operating system that runs when you boot from the Windows Vista or Windows 7 DVD, is a lightweight version of Windows that can run entirely from memory. It can be used to install Windows from local media or a network drive or perform maintenance.

You can find Windows PE on the installation media for Windows Vista, Windows 7, and Windows 8. The Windows PE image itself is a WIM file, sources/boot.wim, on the ISO filesystem. Windows PE can also be found in the Windows Automated Installation Kit (WAIK) inside the WinPE.cab file, which you can extract if you install the cabextract program.

WIM files

A Windows Imaging (WIM) file is an archive. Like some other archive formats such as ZIP, files in WIM archives may be compressed. WIM archives support two Microsoft-specific compression formats: LZX and XPRESS. Both are based on LZ77 and Huffman encoding, and both are supported by wimlib.

Unlike ZIP files, WIM files can contain multiple independent toplevel directory trees known as images. While each image has its own metadata, files are not duplicated for each image; instead, each file is included only once in the entire WIM. Microsoft did this so that in one WIM file, they could do things like have 5 different versions of Windows that are almost exactly the same.

WIM files may contain a integrity table. The integrity table, if it exists, is located at the end of the WIM file and contains SHA1 message digests of 10MB chunks of the WIM.

Microsoft provides documentation for the WIM file format, XPRESS compression format, and LZX compression format. However, there are errors and omissions in some places in their documentation.

Getting Started

wimlib uses the GNU autotools, so it should be easy to install with configure && make && sudo make install, provided that you have libxml2 and libfuse installed. To use wimlib in a program after installing it, include wimlib.h and link your program with -lwim.

wimlib wraps up a WIM file in an opaque WIMStruct structure.

All functions in wimlib's public API are prefixed with wimlib. Most return an integer error code on failure. Use wimlib_get_error_string() to get a string that describes an error code. wimlib also can print error messages itself when an error happens, and these may be more informative than the error code; to enable this, call wimlib_set_print_errors().

wimlib is thread-safe as long as different WIMStruct's are used, with the following exceptions: wimlib_set_print_errors() and wimlib_set_memory_allocator() apply globally, and wimlib_mount() can only be used by one WIMStruct at a time.

To open an existing WIM, use wimlib_open_wim().

To create a new WIM that initially contains no images, use wimlib_create_new_wim().

To add an image to a WIM file from a directory tree on your filesystem, call wimlib_add_image(). This can be done with a WIMStruct gotten from wimlib_open_wim() or from wimlib_create_new_wim().

To extract an image from a WIM file, call wimlib_set_output_dir() to set the output directory, then call wimlib_extract_image().

wimlib supports mounting WIM files either read-only or read-write. Mounting is done using wimlib_mount() and unmounting is done using wimlib_unmount(). Mounting can be done without root privileges because it is implemented using FUSE (Filesystem in Userspace). If wimlib is compiled with the --without-fuse flag, these functions will be available but will fail.

After creating or modifying a WIM file, you can write it to a file using wimlib_write(). Alternatively, if the WIM was originally read from a file, you can use wimlib_overwrite() to overwrite the original file. In some cases, wimlib_overwrite_xml_and_header() can be used instead.

After you are done with the WIM file, use wimlib_free() to free all memory associated with a WIMStruct and close all files associated with it.

To see an example of how to use wimlib, see the file programs/imagex.c in wimlib's source tree.

wimlib supports custom memory allocators; use wimlib_set_memory_allocator() for this.

imagex

wimlib comes with the imagex program, which is documented in man pages.

mkwinpeimg

wimlib comes with the mkwinpeimg script, which is documented in a man page.

Limitations

While wimlib supports the main features of WIM files, wimlib currently has the following limitations:

• wimlib does not support "security data", which describes the access rights of the files in the WIM. This data is very Windows-specific, and it would be difficult to do anything with it. Microsoft's software can still read a WIM without security data, including a boot.wim for Windows PE, but do not expect to be able to use wimlib to image a Windows installation and preserve file attributes.
• There is no support for split WIMs, which have an image divided up between multiple WIM files.
• There is not yet any code to verify that there are no collisions between different files that happen to have the same SHA1 message digest. This is extremely unlikely, but could result in something bad such as a file going missing.
• Alternate stream entries for directory entries are ignored. I'm not sure if these are ever used for anything important.
• Different versions of the WIM file format, if they even exist, are unsupported. Let me know if you notice WIM files with a different version.
• Chunk sizes other than 32768 are unsupported (except for uncompressed WIMs, for which the chunk size field is ignored). As far as I can tell, other chunk sizes are not used in compressed WIMs. Let me know if you find a WIM file with a different chunk size.
• wimlib does not provide a clone of the PEImg tool that allows you to make certain Windows-specific modifications to a Windows PE image, such as adding a driver or Windows component. Such a tool could conceivably be implemented on top of wimlib, although it likely would be hard to implement because it would have to do very Windows-specific things such as manipulating the driver store. wimlib does provide the mkwinpeimg script for a similar purpose, however. With regards to adding drivers to Windows PE, you have the option of putting them anywhere in the Windows PE image, then loading them after boot using drvload.exe.
• There is not yet a way to extract specific files or directories from a WIM file without mounting it, or to add, remove, or modify files in a WIM without mounting it, other than by adding or removing an entire image. I can implement this if requested, but I intend the FUSE mount feature to be used for this purpose, as it is easy to do these things in whatever way you want after the image is mounted.

Currently, Microsoft's image.exe can create slightly smaller WIM files than wimlib when using maximum (LZX) compression because it knows how to split up LZX compressed blocks, which is not yet implemented in wimlib.

wimlib is experimental and likely contains bugs; use Microsoft's imagex.exe if you want to make sure your WIM files are made correctly.

License

The wimlib library is licensed under the GNU Lesser General Public License version 2.1 or later.

imagex and mkwinpeiso are licensed under the GNU General Public License version 3 or later.