wim

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 22, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package wim reads, extracts, and writes Windows Imaging Format (WIM) files, including the solid LZMS-compressed ESD variant distributed by Windows Update and the Media Creation Tool.

It is pure Go and cross-platform, with no cgo or external tools. The container layer (header, resource/blob table, and the XML image catalog) needs no decompression, so images can be enumerated immediately. Reading file contents supports all four WIM compression formats — uncompressed, XPRESS, LZX, and LZMS (including solid resources) — via the sibling lzms/xpress packages and go-winio's LZX decoder.

The package also writes images: Open/Images/OpenImage/ReadFile/ExtractImage on the read side, and Writer (NewWriter/AddImage/AddImageFromWIM/Close) plus CreateFromDir for producing uncompressed, multi-image WIMs such as boot.wim and install.wim.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CreateFromDir 

func CreateFromDir(out io.WriteSeeker, srcDir, imageName string) error

CreateFromDir writes the directory tree at srcDir to out as a single-image, uncompressed WIM named imageName.

func Join added in v0.7.0 

func Join(partPaths []string, outPath string) error

Join merges a spanned ".swm" set back into a single WIM at outPath. It is the inverse of Split (wimlib_join): it reads every part, unions their blob tables by content hash, and writes one standalone WIM with the image metadata resources (from the first part), all file blobs, the XML catalog, and a cleared spanned flag. Parts may be given in any order; they are ordered by header part number.

func Split added in v0.7.0 

func Split(srcPath, outDir, baseName string, maxPartBytes int64) ([]string, error)

Split splits the WIM at srcPath into a spanned set of ".swm" parts, each no larger than maxPartBytes where possible, and returns the written part paths. The first part is "<baseName>.swm" and subsequent parts are "<baseName>2.swm", "<baseName>3.swm", … (the naming Windows Setup expects for an install.swm set).

It is the pure-Go analogue of wimlib_split. Following that on-disk contract: every image's metadata resource lives in the first part; file blobs are bin-packed across parts in sequential order; each part is a standalone WIM with the spanned flag, a shared GUID, part number k of N, the full XML catalog, and a blob table describing only that part's resources (part_number == k). Readers (Join here, or Windows Setup) merge the per-part tables.

A single blob larger than maxPartBytes occupies its own oversized part — individual resources cannot be divided. Splitting a WIM that contains solid resources is unsupported; export it non-solid first.

Types

type Compression 

type Compression int

Compression identifies a WIM's resource compression algorithm. 

const (
	CompressionNone Compression = iota
	CompressionXPRESS
	CompressionLZX
	CompressionLZMS
)

func (Compression) String 

func (c Compression) String() string

type File 

type File struct {
	Name           string
	ShortName      string
	Attributes     uint32
	Size           int64
	Hash           [20]byte
	CreationTime   time.Time
	LastAccessTime time.Time
	LastWriteTime  time.Time
	// contains filtered or unexported fields
}

File is a file or directory within a WIM image.

func (*File) Children 

func (f *File) Children() []*File

Children returns a directory's entries (nil for non-directories).

func (*File) IsDir 

func (f *File) IsDir() bool

IsDir reports whether the entry is a directory (and not a directory reparse point).

func (*File) Walk 

func (f *File) Walk(fn func(path string, file *File))

Walk calls fn for f and every descendant, depth-first. The path is built from entry names joined with "/".

type ImageInfo 

type ImageInfo struct {
	Index            int
	Name             string
	Description      string
	DisplayName      string
	Flags            string
	Edition          string
	Architecture     string
	InstallationType string
	ProductName      string
	DirCount         int64
	FileCount        int64
	TotalBytes       int64
	Languages        []string
	// WindowsXML is the verbatim "<WINDOWS>…</WINDOWS>" fragment from the source
	// catalog (empty when the image has no <WINDOWS> element). It is carried
	// loss-lessly through the writer so a rebuilt WIM keeps every Windows-specific
	// property — INSTALLATIONTYPE, EDITIONID, ARCH, LANGUAGES, VERSION,
	// SERVICINGDATA, WIMBOOT, etc. — that Windows Setup reads to select editions
	// and detect WinPE. Without it, remastered media loses this metadata.
	WindowsXML string
}

ImageInfo describes a single image within a WIM, parsed from the XML catalog.

type Info 

type Info struct {
	Version     uint32
	Compression Compression
	ChunkSize   uint32
	ImageCount  int
	BootIndex   int
	PartNumber  int
	TotalParts  int
	Solid       bool
	GUID        [16]byte
}

Info summarizes a WIM's header.

type Updater added in v0.7.0 

type Updater struct {
	// contains filtered or unexported fields
}

Updater edits a WIM's XML image catalog in place. It is the pure-Go analogue of wimlib_get_image_property / wimlib_set_image_property + wimlib_overwrite: property edits touch only the catalog, never the file blobs or metadata resources, so committing appends a rewritten XML resource and repoints the header at it.

The headline use is the Windows 11 requirement bypass — setting WINDOWS/INSTALLATIONTYPE to "Server" on every image makes Windows Setup skip the TPM/vTPM/Secure Boot/RAM/CPU appraisal. It requires that the catalog carry a <WINDOWS> element to edit, which the writer now preserves.

Only uncompressed XML catalogs are supported (the standard for install.wim / boot.wim); OpenForUpdate returns an error for a compressed catalog.

func OpenForUpdate added in v0.7.0 

func OpenForUpdate(path string) (*Updater, error)

OpenForUpdate opens the WIM at path for read-write catalog and file editing.

func (*Updater) AddFile added in v0.7.0 

func (u *Updater) AddFile(image int, wimPath string, content []byte) error

AddFile schedules creating or replacing the file at wimPath (slash-separated, relative to the image root) in the given 1-based image with content. Parent directories are created as needed. The change is applied by Commit.

func (*Updater) Close added in v0.7.0 

func (u *Updater) Close() error

Close releases the underlying file. Call it whether or not Commit succeeded.

func (*Updater) Commit added in v0.7.0 

func (u *Updater) Commit() error

Commit writes the edited catalog back to the file. The new XML resource is appended at end-of-file and the header's XMLData descriptor is repointed at it (append-overwrite, like wimlib); the old catalog bytes become unreferenced slack. Any integrity table is dropped, since appended data invalidates it.

func (*Updater) Images added in v0.7.0 

func (u *Updater) Images() []ImageInfo

Images returns the current (possibly edited) catalog.

func (*Updater) RemoveFile added in v0.7.0 

func (u *Updater) RemoveFile(image int, wimPath string) error

RemoveFile schedules deleting the file or directory at wimPath in the given 1-based image. Applied by Commit.

func (*Updater) SetProperty added in v0.7.0 

func (u *Updater) SetProperty(image int, key, value string) error

SetProperty sets an image property by key. Supported keys are the top-level catalog fields NAME, DESCRIPTION, FLAGS, DISPLAYNAME, and single-level children of <WINDOWS> addressed as "WINDOWS/<TAG>" (e.g. "WINDOWS/INSTALLATIONTYPE"). image is 1-based.

func (*Updater) SetPropertyAll added in v0.7.0 

func (u *Updater) SetPropertyAll(key, value string) error

SetPropertyAll sets key=value on every image. This is how the Win11 bypass applies WINDOWS/INSTALLATIONTYPE=Server across all editions in one call.

type WIM 

type WIM struct {
	// contains filtered or unexported fields
}

WIM is an opened WIM/ESD file.

func Open 

func Open(path string) (*WIM, error)

Open opens the WIM/ESD file at path.

func OpenReaderAt 

func OpenReaderAt(r io.ReaderAt, size int64) (*WIM, error)

OpenReaderAt opens a WIM/ESD from r. size is the total file size (used for bounds checking); pass 0 if unknown.

func (*WIM) Close 

func (w *WIM) Close() error

Close closes the underlying file if Open created it.

func (*WIM) ExtractImage 

func (w *WIM) ExtractImage(index int, destDir string) error

ExtractImage extracts the 1-based image index to destDir, creating files and directories. Security descriptors, alternate data streams, and reparse points are not applied.

func (*WIM) ImageCount 

func (w *WIM) ImageCount() int

ImageCount returns the number of images in the WIM.

func (*WIM) Images 

func (w *WIM) Images() []ImageInfo

Images returns the images described by the WIM's XML catalog.

func (*WIM) Info 

func (w *WIM) Info() Info

Info returns the WIM header summary.

func (*WIM) OpenImage 

func (w *WIM) OpenImage(index int) (*File, error)

OpenImage parses the directory tree of the 1-based image index and returns its root directory. The image's metadata is decompressed on demand.

func (*WIM) ReadFile 

func (w *WIM) ReadFile(f *File) ([]byte, error)

ReadFile returns the full contents of a regular file within an image. It returns an empty slice for an empty file (zero hash).

func (*WIM) XML 

func (w *WIM) XML() string

XML returns the raw (UTF-8) XML catalog.

type Writer 

type Writer struct {
	// contains filtered or unexported fields
}

Writer assembles a multi-image, uncompressed WIM: a header placeholder, then per-image file blobs (deduplicated by SHA-1) and metadata resources, and finally the blob table, XML catalog, and a header rewrite. Call AddImage once per image, then Close. out must be seekable.

func NewWriter 

func NewWriter(out io.WriteSeeker) (*Writer, error)

NewWriter starts an uncompressed WIM, reserving the header.

func NewWriterCompressed added in v0.6.1 

func NewWriterCompressed(out io.WriteSeeker, comp Compression) (*Writer, error)

NewWriterCompressed starts a WIM whose file resources are compressed with comp (CompressionNone writes them raw). boot.wim must be compressed for the firmware to RAM-disk-load it at boot.

func (*Writer) AddImage 

func (w *Writer) AddImage(srcDir, name string) error

AddImage appends the directory tree at srcDir as a new image named name.

func (*Writer) AddImageFromWIM 

func (w *Writer) AddImageFromWIM(src *WIM, index int, name string) error

AddImageFromWIM copies the 1-based image index from src into the WIM being written, as a new image named name. Blob data is streamed directly from src (no extraction to disk), deduplicated by SHA-1, and the directory tree is rebuilt preserving file attributes and the three timestamps.

Blobs are written in two passes: first the directory tree is planned (and the set of unique blobs collected), then the blobs are copied in source-storage order. The ordering is essential for solid resources: their chunks are large and the reader caches only the most-recently-decompressed chunk, so reading blobs in tree order (which does not match the solid layout) would re-decompress the same chunks repeatedly. Reading in ascending solid offset decompresses each chunk exactly once.

func (*Writer) Close 

func (w *Writer) Close() error

Close writes the blob table, XML catalog, and final header.

func (*Writer) SetBootIndex added in v0.6.1 

func (w *Writer) SetBootIndex(n int)

SetBootIndex marks the 1-based image number as the bootable image. The header's BootIndex and BootMetadata fields are written during Close. Call with 0 to produce no boot image (the default).

Source Files

View all Source files

Directories

Path Synopsis
Package lzms implements a pure-Go decompressor for Microsoft's LZMS compression format, used by solid/ESD WIM resources.
 Package lzms implements a pure-Go decompressor for Microsoft's LZMS compression format, used by solid/ESD WIM resources.
Package lzx implements an LZX compressor for WIM resources (encode side).
 Package lzx implements an LZX compressor for WIM resources (encode side).
Package xpress also implements the XPRESS (LZ77 + Huffman) compressor, the counterpart to Decompress.
 Package xpress also implements the XPRESS (LZ77 + Huffman) compressor, the counterpart to Decompress.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.