Format:PyInstaller archive (CArchive and PYZ)
| 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(hex4D 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
_MEIxxxxxxat 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 andFailed to extractare bootloader markers. Unverified: exact set of strings per release; compare two PyInstaller majors. - The cookie names the Python shared library (for example
python313.dllorlibpython3.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
- Find the cookie, compute the archive start, read the TOC, inflate entries. Extractors such as pyinstxtractor do exactly this.
- Entries of type
sandm/Mhold 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 astruct-like entry that kept it). See Format:PYC (Python compiled bytecode)#Header. - Unmarshal PYZ entries only with the same Python minor version the cookie states; marshal data of another version can misparse or crash.
- The entry points are the
sentries (the main script andpyi_rth_*runtime hooks); the modules the author wrote are in the PYZ among the standard library and third-party packages.
Pitfalls
- Newer PyInstaller (6.x) can store compiled modules for the frozen importer outside the PYZ, and optionally keeps libraries in
_internal/(one-folder). The cookie scan still works. - Encrypting PYZ with
--keywas removed in PyInstaller 6.0; older builds use AES with a key in apyimod00_crypto_keymodule (Unverified: format; check a 5.x build). - Bytecode of the target Python version must be supported by your decompiler; see the PYC page for magic numbers.
- The bootloader builds the cookie magic at run time, so the 8 bytes appear only in the appended cookie, never as a literal in the bootloader code (Fact:PyInstaller archive (CArchive and PYZ)/behavior/Bootloader scans for the cookie without storing the magic); signed or padded executables can have bytes after the cookie, so compute the overlay as pkg_length plus the tail, as pyinstxtractor does.
- PyInstaller 2.0 archives have a 24-byte cookie without the library name (Fact:PyInstaller archive (CArchive and PYZ)/identification/Cookie variants of PyInstaller 2.0 and 2.1 or later).
- Run-time behaviour of onefile builds (extraction directory
_MEI+ PID + random,sys._MEIPASS, the_PYI_*environment variables) is in Fact:PyInstaller archive (CArchive and PYZ)/behavior/Onefile temp directory MEIPASS and environment variables; bootstrapm/Mentries are executed first (Fact:PyInstaller archive (CArchive and PYZ)/behavior/Bootloader runs m and M entries then installs the PYZ). Dependency entries and optimization codes: Fact:PyInstaller archive (CArchive and PYZ)/behavior/Dependency entries and script optimization codes.
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.pyandwriters.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.