fo4-save-cleaner

Remove mod change forms and clean Papyrus script instances from Fallout 4 save files (.fos).

Built to recover saves that crash or show "content no longer present" warnings after removing mods.

Features

• Auto-detects vanilla vs mod plugins (Fallout4.esm, DLCs, Creation Club are preserved)
• Removes mod-related change forms (REFR, NPC_, ARMO, WEAP, etc.)
• Cleans Papyrus VM script instances that reference removed forms (prevents crashes)
• Interactive save picker and mod selector with Rich CLI
• Byte-perfect roundtrip — original save structure is fully preserved
• Original save file is never modified (writes to _clean.fos)

Setup

# Install uv (if not already installed)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Clone and install
git clone https://github.com/pub-struct/fo4-save-cleaner.git
cd fo4-save-cleaner
uv sync

Usage

Interactive mode (recommended)

# Auto-detect saves folder, pick a save, choose mods to remove
uv run fo4-save-cleaner

Direct file

# Analyze only (no changes)
uv run fo4-save-cleaner "path/to/Save1.fos" --analyze-only

# Remove all mod change forms
uv run fo4-save-cleaner "path/to/Save1.fos" --remove-all-mods

# Custom output path
uv run fo4-save-cleaner "path/to/Save1.fos" -o "Save1_clean.fos"

How it works

1. Parse the .fos binary save (header, plugins, file map, global data, change forms, Papyrus VM)
2. Classify plugins as vanilla/DLC/CC or mod based on known plugin names
3. Identify change forms belonging to mod plugins via RefID resolution
4. Remove mod change forms from the save
5. Clean Papyrus — parse the GD3 Papyrus VM block, find script instances referencing removed forms, zero out their RefIDs (marking them as "unattached" for the game's garbage collector)
6. Write the cleaned save with all internal offsets and structures preserved

Save file format

The tool handles the full FO4 save format:

• FO4_SAVEGAME header + RGBA screenshot
• Plugin lists (regular + light/ESL)
• File map (10 section offsets)
• Global Data blocks (GD1, GD2, GD3)
• Change Forms with 3-byte RefID encoding
• Papyrus VM state (GD3 block 1001): string table, script/struct definitions, 275K+ script instance headers
• RefID array + unknown table

Papyrus format details

Reverse-engineered from FallrimTools by mdfairch:

• String table: u16 length + UTF-8 bytes (WStringElement format)
• TString indices: u32 for FO4 with form_version > 61
• Element IDs: 8 bytes (64-bit) for FO4
• RefIDs: 3 bytes big-endian (same encoding as change form RefIDs)
• Script definitions: tstring(name) + tstring(parent) + u32(count) + [tstring + tstring]...
• Instance headers: eid(8) + tstring(4) + u16 + u16 + refID(3) + u8 [+ u8 if FO4 flag]

Limitations

• Light plugins (.esl/FE-slot) have basic support — complex FE interactions may not be fully resolved
• Inventory sub-items inside vanilla containers/NPCs are not individually cleaned
• Quest progress stored in global data is preserved (removing it could cause instability)
• The tool only cleans script instance RefIDs, not the full script data/variables

Credits

• Papyrus VM format based on FallrimTools by mdfairch
• FO4 save format documentation from the UESP wiki and community research

License

MIT