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:PyInstaller archive (CArchive and PYZ)

From ReverseEngineering.wiki
Format
Developer PyInstaller team
Magic 4D 45 49 0C 0B 0A 0B 0E (cookie, near the end of the file); 50 59 5A 00 (PYZ)
Endianness big (network byte order)
License GPL-2.0-or-later with bootloader exception
Website https://pyinstaller.org
On this wiki Facts · Code · Notes · Topics

The container PyInstaller appends to its bootloader executable: a CArchive (PKG) with a table of contents, closed by a 88-byte cookie that starts with the magic MEI\x0c\x0b\x0a\x0b\x0e and records the Python version, and inside it a PYZ archive of zlib-compressed marshalled module code objects.

Identification

  • The program is a small C bootloader (PE, ELF or Mach-O) with the archive appended as an overlay. Search the file from the end backwards for the 8-byte cookie magic MEI\x0c\x0b\x0a\x0b\x0e (hex 4D 45 49 0C 0B 0A 0B 0E); the cookie is the last structure of the file (a code-signing blob or other tail data may follow it, so scan, do not assume the last bytes) (Fact:PyInstaller archive (CArchive and PYZ)/magic/CArchive cookie magic).
  • A one-file build unpacks itself to a temporary directory named _MEIxxxxxx at start-up (sys._MEIPASS); a one-folder build keeps the same archive in the executable and the files next to it. Strings such as _PYI_ARCHIVE_FILE, pyi- options and Failed to extract are bootloader markers. Unverified: exact set of strings per release; compare two PyInstaller majors.
  • The cookie names the Python shared library (for example python313.dll or libpython3.13.so.1.0) and an integer Python version, so the interpreter version is known without running anything (Fact:PyInstaller archive (CArchive and PYZ)/struct/CArchive cookie).

CArchive layout

All integers are big-endian. The archive is the byte range [cookie_end - pkg_length, cookie_end). Offsets in the cookie and in the TOC are relative to the archive start, not to the file start (an executable overlay therefore needs the start computed from the cookie).

Part Contents
Entry data each entry zlib-compressed (flag 1) or stored (flag 0), one after the other
TOC variable-size entries, each padded to a multiple of 16 bytes
Cookie char magic[8]; uint32 pkg_length; uint32 toc_offset; uint32 toc_length; uint32 python_version; char python_libname[64] (88 bytes)

TOC entry: uint32 entry_length; uint32 offset; uint32 length (stored size); uint32 uncompressed_length; uint8 compression_flag; char typecode; char name[] (NUL-padded UTF-8) (Fact:PyInstaller archive (CArchive and PYZ)/struct/CArchive TOC entry). python_version is major100+minor (for example 313); very old PyInstaller 2.0 archives have a shorter cookie without the library name and a decimal major10+minor.

Type codes

See Fact:PyInstaller archive (CArchive and PYZ)/enum/CArchive typecodes: b binary, x data, z or Z the PYZ archive, s entry-point script (a marshalled code object, no pyc header), m/M module/package (marshalled code object), d dependency, o runtime option (for example v, u, W ignore), l splash resources, n symbolic link. Build-time TOC types s1/s2 are optimization levels of s. Entries of type o and d carry no data and may repeat.

PYZ archive

The PYZ entry (usually named PYZ-00.pyz) is a header followed by data and a marshalled TOC: bytes 0-3 PYZ\0, bytes 4-7 the Python bytecode magic number of the interpreter that built it (the first four bytes of a Format:PYC (Python compiled bytecode) file), bytes 8-11 a big-endian int32 TOC offset, 4 unused bytes. The TOC is a Format:Marshal (Python) list of (name, (type, offset, length)) with type 0 module, 1 package, 2 data (deprecated), 3 PEP 420 namespace package. Each module is zlib.compress(marshal.dumps(code_object)) with no pyc header; the header must be rebuilt before a decompiler can read it (Fact:PyInstaller archive (CArchive and PYZ)/struct/PYZ header).

Extraction recipe

  1. Find the cookie, compute the archive start, read the TOC, inflate entries. Extractors such as pyinstxtractor do exactly this.
  2. Entries of type s and m/M hold bare marshalled code objects in PyInstaller 5.3 and later (older versions kept a 4-byte magic or the whole pyc header): prepend a pyc header whose magic comes from the PYZ header bytes 4-7 (or from a struct-like entry that kept it). See Format:PYC (Python compiled bytecode)#Header.
  3. Unmarshal PYZ entries only with the same Python minor version the cookie states; marshal data of another version can misparse or crash.
  4. The entry points are the s entries (the main script and pyi_rth_* runtime hooks); the modules the author wrote are in the PYZ among the standard library and third-party packages.

Pitfalls

Code & repositories

See the repository list below (pyinstaller and pyinstxtractor).

  • https://github.com/pyinstaller/pyinstaller @ ad07220e06931adbd54d4ad1b7ef955ef2a73713 · license: GPL-2.0-or-later WITH Bootloader-exception (declared by the contributor; GitHub's detector did not recognize COPYING.txt)
    PyInstaller itself: archive readers/writers (PyInstaller/archive), PYZ loader, C bootloader (bootloader/src) with the cookie and TOC definitions.
    Tested on: source read, not run: Read the source at this commit (6.22.3); not built or run. · checked 2026-10-18; last activity 2026-10-16
  • https://github.com/extremecoders-re/pyinstxtractor @ 815d31cf26bc71e62f851b2e549452e7b7c9dd98 · license: GPL-3.0
    pyinstxtractor (GPL-3.0): extracts a PyInstaller executable, rebuilds pyc headers, handles cookie variants of PyInstaller 2.0 to 5.x.
    Tested on: source read, not run: Read the script at this commit; not run. · checked 2026-10-18; last activity 2026-07-22

Evidence & references

  • pyinstaller/pyinstaller commit ad07220e06931adbd54d4ad1b7ef955ef2a73713 (version 6.22.3): PyInstaller/archive/readers.py and writers.py (CArchiveReader/CArchiveWriter, ZlibArchiveWriter), PyInstaller/loader/pyimod01_archive.py, bootloader/src/pyi_archive.h.
  • extremecoders-re/pyinstxtractor commit 815d31cf26bc71e62f851b2e549452e7b7c9dd98 pyinstxtractor.py (GPL-3.0): cookie scan, version handling, header repair.