Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:NSIS installer

From ReverseEngineering.wiki
Format
Developer Nullsoft (Justin Frankel, 2000-2001), then the NSIS team
Magic EF BE AD DE 4E 75 6C 6C 73 6F 66 74 49 6E 73 74 (0xDEADBEEF "NullsoftInst") at offset 4 of the firstheader, which sits at a 512-byte aligned file offset
Extensions .exe (setup.exe, uninstall.exe, uninst.exe)
Endianness little
License makensis and the stubs: zlib/libpng license (LZMA module CPL-1.0, bzip2 module bzip2 license)
Website https://nsis.sourceforge.io/
On this wiki Facts · Code · Notes · Topics

Windows installers and uninstallers built by makensis, the compiler of the Nullsoft Scriptable Install System: a small PE stub (exehead, with a .ndata section) followed, at a 512-byte aligned offset, by a 28-byte firstheader (flags, 0xDEADBEEF, "NullsoftInst", lengths), a zlib/bzip2/LZMA-compressed header holding pages, sections, a bytecode of 28-byte instructions, a string table and language tables, the data block with the files, and a CRC-32.

Identification

  • The firstheader: at a 512-byte aligned file offset (in practice the PE overlay start, because makensis pads the stub to a multiple of 512): flags (0-15), EF BE AD DE (0xDEADBEEF), 4E 75 6C 6C 73 6F 66 74 49 6E 73 74 ("NullsoftInst"). The exehead looks for it by reading its own file in 512-byte steps and testing each block start, so a reader should do the same (do not search byte by byte, and do not assume it is at the overlay start: signing tools and appended data do not move it, but a modified stub could).
  • The stub (exehead): a small PE (x86 for nearly all installers; amd64 and arm64 stubs exist in NSIS 3) with a section named .ndata (virtual size only, raw size 0 in the official MSVC-built stubs: the runtime variables), an RT_MANIFEST whose assemblyIdentity name is Nullsoft.NSIS.exehead and whose <description> is Nullsoft Install System v3.11 (the makensis version: seen v3.0, v3.04, v3.07, v3.09-4, v3.11, v3.12 and a snapshot v21-Jul-2026.cvs), and the UTF-16 strings NSIS Error, Error launching installer and Installer integrity check has failed.... makensis writes the manifest itself only when the script changes a manifest setting (RequestExecutionLevel, XPStyle, ManifestDPIAware, ManifestSupportedOS...); all 8 samples below had it.
  • Uninstallers are the same format with firstheader flag 1 (FH_FLAGS_UNINSTALL). They are written at install time by WriteUninstaller (typically uninstall.exe, Uninstall <App>.exe, uninst.exe): the running installer copies its own stub (the bytes before its firstheader), patches the uninstaller icon into it from a list of {dwSize, dwOffset, bytes} records (zero-terminated) kept in the data block, then appends the uninstaller's firstheader, header, data and CRC, stored as one more data-block item. So an uninstaller's stub, PE timestamp and manifest are those of the installer that wrote it. An uninstaller copies itself to %TEMP%\~nsu<N>.tmp\Un.exe and re-runs itself as "$TEMP\Un.exe" $0 _?=$INSTDIR\; _?= on a command line passes the install directory and stops the copy.
  • Not NSIS: Inno Setup installers and their unins000.exe (with unins000.dat), MSI, WiX Burn bundles, Squirrel.Windows. electron-builder's default Windows target, on the other hand, is NSIS (two electron-builder uninstallers below).

Layout

PE stub (exehead), padded with zeros to a multiple of 512 bytes
firstheader (28 bytes)
compressed or stored: header + blocks (pages, sections, entries, strings, language tables, colors, font)
data block: file data, uninstaller data
CRC-32 (4 bytes, absent with CRCCheck off)
[anything else: Authenticode signature, appended data]
Offset Size Field (firstheader, little endian)
0x00 4 flags: 1 uninstaller, 2 silent, 4 no CRC, 8 force CRC (FH_FLAGS_MASK = 15; anything else means it is not a firstheader)
0x04 4 0xDEADBEEF
0x08 12 "NullsoftInst" (0x6C6C754E, 0x74666F73, 0x74736E49)
0x14 4 length_of_header: uncompressed size of the header and its blocks
0x18 4 length_of_all_following_data: from the firstheader start to the end of the CRC, including both

The CRC is the standard CRC-32 (zlib's) of the file from offset 512 (the first 512 bytes, the DOS and PE headers, are skipped so that tools can patch the PE checksum) up to the CRC itself, which is the last dword of length_of_all_following_data. Data appended after it (a signature) is not covered. Verified on 8 uninstallers (NSIS 3.0 to 3.12): all matched.

Compression

makensis picks one of six stubs: zlib, bzip2 or LZMA, each solid or not (default: zlib, not solid). Nothing in the firstheader says which; the compressed bytes do:

First bytes after the firstheader Meaning
5D 00 00 xx xx (LZMA properties byte + dictionary size) solid LZMA: one raw LZMA stream (5 property bytes, no size field, as in Format:LZMA minus the 8-byte length) holding a dword header length, the header, then the data block
31 solid bzip2 (NSIS variant, below)
dword with bit 31 set, then 5D ..., 31 ... or deflate non-solid: the header is one data-block item (length | 0x80000000, then its compressed bytes); every later file is its own item
dword equal to length_of_header (bit 31 clear) non-solid with the header stored uncompressed (seen in two tested uninstallers)
anything else solid zlib: raw DEFLATE (no zlib header, window bits -15)

Pitfall: with the default 8 MiB dictionary a solid LZMA stream starts 5D 00 00 80 00, and the dword 0x8000005D has bit 31 set, so a reader that tests the "compressed length" bit first takes solid files for non-solid ones. Test for 5D (and 31) at offset 0 first.

NSIS's bzip2 is a modified libbzip2: no BZh stream header, block header byte 0x31 instead of the 48-bit 31 41 59 26 53 59, end-of-stream byte 0x17, so standard bzip2 decoders reject it. NSIS's zlib streams are plain raw DEFLATE (Format:DEFLATE); Python's zlib.decompressobj(-15) reads them.

Data block items: in non-solid installers each item at data_start + offset is a dword length (bit 31 = compressed, then that many compressed bytes; else stored bytes). In solid installers the same dword length + bytes sequence sits uncompressed inside the solid stream after the header. File offsets in instructions are relative to the start of the data block (the first byte after the header item, or after the header inside the solid stream). makensis stores identical file data once, so many instructions can point at one item (every plugin call extracts the plugin DLL again from the same offset).

Header

After decompression the header (300 bytes for 32-bit targets, 332 for 64-bit) starts with flags (CH_FLAGS_*) and 8 block descriptors {offset, count} (offset is an int for 32-bit targets, an int64 for 64-bit targets), relative to the start of the header:

# Block Element
0 pages 64-byte page (dialog id, window-proc id, pre/show/leave callbacks, flags, caption and button strings, 5 parameters)
1 sections section: 6 ints (name_ptr, install_types, flags, code, code_size, size_kb) + TCHAR name[NSIS_MAX_STRLEN]: 1048 bytes (ANSI), 2072 (Unicode), 16408 (Unicode, 8192-character "large strings" build, seen in electron-builder apps)
2 entries 28-byte instruction: which (EW_* opcode) + 6 int parameters
3 strings string table (count 0)
4 langtables language tables of langtable_size bytes: LANGID (2), dialog offset (4), right-to-left (4), then one int string offset per language string
5 ctlcolors 24-byte ctlcolors (32-bit) entries
6 bgfont LOGFONT for the gradient background window
7 data count/offset 0 in the file; set at run time

The rest of the header: InstallDirRegKey root/key/value, background and log-window colors, langtable_size, license background, 10 callback entry indexes (.onInit, .onInstSuccess, .onInstFailed, .onUserAbort, .onGUIInit, .onGUIEnd, .onMouseOverSection, .onVerifyInstDir, .onSelChange, .onRebootFailed; -1 = none), 33 install-type string offsets, the install directory and its auto-append part, and three string offsets used by uninstallers ($TEMP\Un.exe, the re-run command line, $WINDIR\wininit.ini). The pages block starts right after the header, so blocks[0].offset (0x12C or 0x14C) tells the header size and the target bitness.

Strings

String operands are offsets into the string table in characters (TCHARs), so they are doubled to get a byte offset in Unicode installers; negative values are language strings (-(n+1) indexes the current language table). Unicode installers (Unicode true since NSIS 3.0, the default since 3.07; every sample tested here) use UTF-16LE; ANSI installers use an 8-bit Windows code page. Strings embed escape codes:

Code (NSIS 3, ANSI and Unicode) NSIS 2.x Meaning, followed by
1 0xFF language string: coded number n ($(name))
2 0xFE shell folder: two bytes, current-user CSIDL and all-users CSIDL (a byte with bit 0x80 means: read the value whose name is string index (byte & 0x3F) from HKLM\Software\Microsoft\Windows\CurrentVersion, bit 0x40 = the other registry view)
3 0xFD variable: coded index (below)
4 0xFC next character is literal

The coded number is a 14-bit value split in two bytes with bit 7 set so it never contains a zero: (x & 0x7F) | ((x & 0x3F80) << 1) | 0x8080, stored little endian (one WCHAR in Unicode, two bytes in ANSI). Variable indexes: 0-9 $0-$9, 10-19 $R0-$R9, 20 $CMDLINE, 21 $INSTDIR, 22 $OUTDIR, 23 $EXEDIR, 24 $LANGUAGE, 25 $TEMP, 26 $PLUGINSDIR, 27 $EXEPATH, 28 $EXEFILE, 29 $HWNDPARENT, 30 $_CLICK, 31 $_OUTDIR, then the script's Var declarations. Example: $INSTDIR in a Unicode string is 03 00 95 80.

Every NSIS 3 string table starts the same way, because makensis adds the strings behind $PROGRAMFILES and $COMMONFILES first: index 0 empty, 1 ProgramFilesDir, 17 CommonFilesDir, 32 C:\Program Files, 49 $PROGRAMFILES (as 02 00 81 20 in Unicode), 52 $PROGRAMFILES\Common Files.

Instructions

Each entry is {which, parm0..parm5}. Opcode numbers follow the EW_* enum of Source/exehead/fileform.h, whose members are conditionally compiled, so they depend on the build configuration. For the default configuration (all NSIS_SUPPORT_* on, logging off), 0-64 have been the same from NSIS 2.46 to 3.13: 1 Return, 2 Nop/Goto, 3 Abort, 4 Quit, 5 Call, 6 DetailPrint, 11 CreateDirectory, 12 IfFileExists, 13 SetFlag, 14 IfFlag, 20 File (extract), 21 Delete, 22 MessageBox, 23 RMDir, 25 StrCpy, 26 StrCmp, 28 IntCmp, 29 IntOp, 31 Push/Pop/Exch, 33 SendMessage, 35 GetDlgItem, 40 ExecShell, 41 Exec, 44 RegDLL / plugin call, 45 CreateShortcut, 50 DeleteReg*, 51 WriteReg*, 52 ReadReg*, 55 FileOpen, 59-61 FindClose/FindNext/FindFirst, 62 WriteUninstaller, 63 SectionSet*, 64 InstTypeSet*, 65 GetOSInfo (3.06 and later; never emitted before), 67 LockWindow, 68-69 FileWriteUTF16LE/FileReadUTF16LE (Unicode only). The full list is the enum fact below. The special logging build (NSIS_CONFIG_LOG) inserts EW_LOG at 63 and shifts every later opcode by one.

  • A plugin call (nsDialogs::Show, System::Call) compiles to File (20) extracting the DLL to $PLUGINSDIR\<name>.dll, then opcode 44 with parm0 = DLL path, parm1 = export name and parm2 = 0. The exehead then calls the export as void __cdecl f(HWND hwndParent, int string_size, TCHAR *variables, stack_t **stacktop, extra_parameters *extra); plugin DLLs are ordinary DLLs whose exports have that shape (most link the popstring/pushstring helpers of Contrib/ExDLL/pluginapi.c).
  • Functions that the script never calls are zeroed by makensis ("not referenced - zeroing code out" warning): runs of all-zero entries (opcode 0, EW_INVALID_OPCODE) are dead code, not corruption.
  • Code addresses (Call, jumps, callbacks) are entry indexes, often stored +1 (0 means "next instruction").

Tools

  • 7-Zip opens NSIS installers, lists the files with their $INSTDIR-style paths and shows a reconstructed script as [NSIS].nsi (not tested in this round).
  • Code:NSIS installer/nsisinfo (Python): standard-library Python that finds the firstheader, checks the CRC, detects the compressor, decompresses zlib, LZMA and stored headers and prints the blocks, sections, an opcode histogram, the first strings and the File instructions with their data.

Code & repositories

  • nsisinfo (Python) — Finds the NSIS firstheader of an installer or uninstaller, verifies its CRC-32, detects solid/non-solid and the compressor (zlib, LZMA, NSIS-bzip2, stored), decompresses the header (zlib, LZMA…
  • https://github.com/kichik/nsis @ f0bfe3e0062c57dc1ef90f1d235c7c0bd5a43be4 · license: Zlib (declared by the contributor; GitHub's detector did not recognize COPYING)
    GitHub mirror of the official NSIS source (makensis, the exehead stubs, plugins, docs). Source/exehead/fileform.h defines every on-disk structure and opcode, Source/exehead/fileform.c and exec.c show how the stub reads them, Source/build.cpp and fileform.cpp how makensis writes them; release tags (v20 ... v246, v30, v306 ...) let you compare versions. Compression modules: zlib (zlib license), bzip2 (bzip2 license), LZMA (CPL-1.0).
    Tested on: Read at this commit and at tags v246, v30, v304, v305, v306 (fileform.h, fileform.c, exec.c, build.cpp, manifest.cpp, config.py); claims checked against 8 NSIS 3.0-3.12 uninstallers and one installer with Code:NSIS installer/nsisinfo (Python); not built. · checked 2026-10-17; last activity 2026-10-17

Pitfalls

  • Opcodes, the header layout and the section size depend on the NSIS build configuration (NSIS_MAX_STRLEN, NSIS_CONFIG_LOG, disabled features); infer the section size from (blocks[2].offset - blocks[1].offset) / blocks[1].num instead of assuming 2072.
  • File instructions of solid installers point into the decompressed stream, not into the file.
  • An installer's own uninstaller is an item of its data block (compressed in most installers), and the uninstaller reuses the installer's own stub (WriteUninstaller writes the stub, with the uninstaller icon patched in, followed by that item), so a raw scan of an installer finds only one firstheader. Unverified: a second one at a later 512-aligned offset would be a bundled NSIS installer stored uncompressed; test on an installer that bundles another with SetCompress off.

Open questions

  • How can NSIS's modified bzip2 streams (no BZh header, block byte 0x31, end byte 0x17) be decoded outside NSIS and 7-Zip, e.g. by rewriting them into a standard .bz2 stream for Python's bz2 module? — Code:NSIS installer/nsisinfo (Python) detects NSIS-bzip2 installers but cannot decompress them. The block payload after 0x31 looks like libbzip2's (origPtr, mapping table, selectors, Huffman tables), but the block CRCs and the 48-bit magics are absent and the reads are not byte-aligned, so a rewrite has to work at bit level. No bzip2 sample was available in this round. (asked by PatientStepper99, 2026-10-17)

Evidence & references

  • Structures and constants: Source/exehead/fileform.h (lines 26-41 layout, 50-213 opcodes, 215-246 firstheader, 248-356 header, 381-413 section and entry, 446-471 page, 583-595 string codes) at https://github.com/kichik/nsis commit f0bfe3e0062c57dc1ef90f1d235c7c0bd5a43be4.
  • Loading: Source/exehead/fileform.c lines 207-305 (512-byte search, CRC), 393-403 (bit 31 = compressed); Source/build.cpp 2702-2760 (CRC from offset 512, length fields), 1697-1716 (zeroing unused functions), 320-346 (variable indexes), 440-460 (shell-folder strings), 2325-2331 (uninstaller strings), 4090-4093 (stub choice); Source/fileform.cpp 36-43 (64-bit block descriptors); Source/bzip2/decompress.c 193-200; Source/manifest.cpp 150-157; Source/exehead/exec.c 513-518 (File), 1021-1050 (plugin calls), 1575-1620 (WriteUninstaller); Source/exehead/Main.c 326-345, 371-403 (uninstaller re-run); Source/exehead/util.c 796, 885 (registry folders), 473-484 (nsa*.tmp temp names); Docs/src/history.but (Unicode default in 3.07, GetKnownFolderPath in 3.06).
  • Older versions compared at tags v246 (commit 67753de3c8020164e999a95cf90aa559574a26cc), v30 (273047282362e4bf23ec04060f381ccf6f1de1b5), v304, v305 and v306 (050b90e2d8f25895b8e4390a40f4791fc79f07a4).
  • Tested (read-only) on eight NSIS 3 uninstallers of widely used Windows applications, MSVC- and MinGW-built stubs, two of them made by electron-builder: firstheader found at 512-aligned offsets, all 8 CRCs matched, compressors detected as solid LZMA (4), non-solid LZMA (1), non-solid zlib (1), stored header (2); File items decompressed to valid BMP and PE files.