wadlib

Python 3.12+ library and CLI toolkit for reading, writing, and analysing id Software WAD files — Doom, Doom II, Heretic, Hexen, Strife, and source-port mods (ZDoom, GZDoom, PK3, UDMF).

Full documentation →

Installation

pip install wadlib

For FUSE filesystem mounting:

pip install "wadlib[fuse]"

For development:

git clone https://github.com/rembish/wadlib
cd wadlib
make install   # creates .venv, installs with dev + release deps

Quick start

from wadlib import WadFile

# Open a single WAD
with WadFile("DOOM2.WAD") as wad:
    print(wad.wad_type)        # WadType.IWAD
    print(len(wad.maps))       # 32
    print(wad.maps[0])         # MAP01

# Layer a PWAD on top — PWAD lumps shadow base-WAD lumps by name
with WadFile.open("DOOM2.WAD", "SIGIL_II.WAD") as wad:
    for m in wad.maps:
        print(m, "—", len(m.things), "things")

from wadlib import WadArchive

# Read
with WadArchive("DOOM2.WAD") as wad:
    print(wad.namelist())
    data = wad.read("PLAYPAL")

# Append — modify in place (last-wins semantics match Doom engine)
with WadArchive("mod.wad", "a") as wad:
    wad.replace("PLAYPAL", new_palette)
    wad.writestr("NEWLUMP", data)

# Write — create from scratch with namespace markers
with WadArchive("patch.wad", "w") as wad:
    wad.writemarker("F_START")
    wad.writestr("MYFLOOR", flat_bytes)
    wad.writemarker("F_END")

# CLI
wadcli --wad DOOM2.WAD info
wadcli --wad DOOM2.WAD list maps
wadcli --wad DOOM2.WAD export map MAP01 map01.png
wadcli --wad DOOM2.WAD export sound DSPISTOL pistol.wav
wadcli --wad DOOM2.WAD check

For the full API, CLI reference, and how-to guides see the documentation site.

Stability and coverage

Supported games

Examples

The examples/ directory contains runnable scripts for common workflows:

Requirements

• Python 3.12+
• Pillow >= 9.2