pywimparser 0.1.0

Python library for parsing and extracting Microsoft WIM archives via libwim

pywimparser

pywimparser is a Python library for reading Microsoft WIM archives.

It focuses on:

• parsing as much metadata as possible
• listing files/directories inside images
• extracting full images or selected paths

This project is read-only for WIM operations. It does not create or modify WIM files.

Backend Model

pywimparser has two runtime paths:

• Native libwim backend (ctypes, raw C API)
  • full metadata traversal
  • robust extraction support
  • supports XPRESS, LZX, and LZMS through libwim
• Pure Python fallback
  • parses core WIM structures directly
  • can list/extract uncompressed resources
  • cannot fully decompress entropy-coded XPRESS/LZX/LZMS resources

Use WimParser.parse_backend to see which backend was used for a parse call.

Features

• Archive-level metadata
  • header fields (signature, version, flags, chunk size, GUID, parts, image count)
  • lookup/offset table entries
  • XML document (when available)
• Image metadata
  • name, description, display name/description
  • file/dir counts and total bytes (when present)
  • selected Windows metadata from XML (when present)
• Filesystem metadata
  • path, type, timestamps, attributes, size, packed size, stream hash
• Extraction
  • extract_all() for an image
  • extract([...]) for selected paths

Platform Support

• Packaging:
  • pywimparser is distributed as a pure-Python wheel (py3-none-any) plus sdist.
  • The same wheel is installable on Linux/macOS/Windows for Intel and ARM.
• CI coverage:
  • Linux: x64 + arm64
  • macOS: Intel + Apple Silicon
  • Windows: x64 + arm64
• Native libwim backend CI:
  • validated on Linux x64 + arm64
  • other platforms use the pure-Python fallback unless libwim is installed and discoverable

Installation

From PyPI:

pip install pywimparser

For full extraction/compression support, ensure libwim is installed and discoverable.

Build libwim Without ntfs-3g

The repository includes scripts/build_libwim.sh to build shared libwim with:

• --without-ntfs-3g
• --without-fuse
• --enable-shared
• --disable-static

This keeps usage in the libwim dual-license path that allows LGPL option when ntfs-3g is not linked.

./scripts/build_libwim.sh

After build, point pywimparser to the library:

export PYWIMPARSER_WIMLIB_PREFIX="$(pwd)/.vendor/wimlib"
# or:
export PYWIMPARSER_LIBWIM="$(pwd)/.vendor/wimlib/lib/libwim.so"

Quick Start

from pywimparser import WimParser

parser = WimParser("install.wim")
metadata = parser.parse()

print(parser.parse_backend)              # "libwim-c" or "python"
print(parser.native_backend_available)   # True if libwim is usable
print(metadata.header.compression_format)

entries = parser.list_entries(image_index=1)
print(entries[0].path)

parser.extract_all("./out", image_index=1)
parser.extract(["Windows/System32/notepad.exe"], "./out", image_index=1)

CLI

pywimparser info install.wim
pywimparser list install.wim --image 1
pywimparser extract install.wim ./out --image 1
pywimparser extract install.wim ./out --image 1 --path Windows/System32/cmd.exe

Development

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install package + dev tooling:

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Run tests:

python -m unittest discover -s tests -v

Fixture notes are in tests/fixtures/README.md.

Build Artifacts

Build wheel + sdist:

python -m build

GitHub Actions / PyPI Readiness

The repository includes workflows for:

• CI (install package, run tests, build artifacts)
• Publish (build sdist/wheel, publish with trusted publishing)

Before releasing publicly:

• confirm project.urls in pyproject.toml
• choose and document your versioning policy
• configure your PyPI trusted publisher or token flow

Tracked checklist: see NEXT_STEPS.md.

Public API

Main class:

• WimParser(path)

Methods:

• parse(force_reload=False)
• list_entries(image_index=1)
• extract_all(destination, image_index=1)
• extract(paths, destination, image_index=1)

Properties:

• parse_backend
• native_backend_available
• rust_backend_available (compatibility alias)
• extraction_available

License

pywimparser is licensed under MIT.

libwim is third-party software with its own license terms. See THIRD_PARTY_NOTICES.md.

This README is technical guidance, not legal advice.