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:NumPy NPY and NPZ

From ReverseEngineering.wiki
Format
Developer NumPy
Magic 93 4E 55 4D 50 59 (\x93NUMPY)
Extensions .npy, .npz
Endianness header length little-endian; data order given by descr
License BSD-3-Clause
On this wiki Facts · Code · Notes · Topics

NumPy's array files: .npy is the magic \x93NUMPY, a version byte pair, a little-endian header length, a Python-literal dict (descr, fortran_order, shape) padded to a multiple of 64 bytes, then the raw array bytes; .npz is a ZIP of .npy members.

Layout of .npy

numpy/lib/_format_impl.py (numpy 3e225b2; numpy/lib/format.py is only a re-export shim) defines the format. The file starts with the 6-byte MAGIC_PREFIX \x93NUMPY (line 179), then one byte major and one byte minor version (MAGIC_LEN = 8). The header length field follows, then that many bytes of header, then the array data.

Versions and their length field (the _header_size_info table, lines 188-191): 1.0 uses <H (little-endian uint16, header at most 65535 bytes, text decoded as latin1); 2.0 uses <I (uint32, latin1); 3.0 uses <I with utf8 text, needed for structured dtypes with non-latin1 field names. Writers use 1.0 unless the header does not fit, and use 3.0 only when the field names need utf8 (see _write_array_header, lines 427-440).

Header text

The header is the text of a Python dict literal with exactly the keys descr (a dtype description such as '<f4' or a list of field tuples), fortran_order (bool) and shape (tuple of ints). Readers parse it with ast.literal_eval and reject any other key set (EXPECTED_KEYS, lines 654-700). It ends with a newline and is padded with spaces so that magic (8) plus length field (2 or 4) plus header length is a multiple of ARRAY_ALIGN = 64 (lines 181, 405-407), so the data starts on a 64-byte boundary and can be memory-mapped.

Data

After the header come the raw bytes in C order, or Fortran order when fortran_order is true; the count is prod(shape) times the dtype itemsize, and shape () means one element. If the dtype contains Python objects (dtype.hasobject), the data part is instead a Python pickle of the array, which runs code when loaded (see Format:Python pickle).

.npz

np.savez / savez_compressed write a ZIP (ZIP_STORED, or ZIP_DEFLATED when compressed; zip64 forced) whose members are <key>.npy, one array each (numpy/lib/_npyio_impl.py savez at line 756 onward, member name key + '.npy'). np.load recognises a ZIP by the first four bytes PK\x03\x04 (or PK\x05\x06 for an empty zip), a plain array by the \x93NUMPY prefix, and treats anything else as a pickle, which it refuses unless allow_pickle is true (lines 453-493). allow_pickle defaults to False in load; the header parser also refuses headers over a size limit (_MAX_HEADER_SIZE = 10000 characters) unless the caller raises max_header_size.

Reversing notes

A .npy is trivial to parse by hand: read 8 bytes, the length, the dict text; the rest is the array. Weights shipped as .npy/.npz in games and apps are often float32/float16 arrays; the descr string gives byte order (< little, > big, | not applicable). See Technique:Identifying machine-learning models in applications. Unverified: pickled object arrays inside .npz are loaded only when allow_pickle=True, so for untrusted files use allow_pickle=False and check dtype.hasobject in the header first.

Code & repositories

See the linked repository on this page.

  • https://github.com/numpy/numpy @ 3e225b263fd62b68f657b2ad4522932618247aa8 · license: BSD-3-Clause (declared by the contributor for the files used; GitHub reports BSD-3-Clause (read from LICENSE.txt; GitHub's detector did not classify it) for the repository)
    numpy/lib/_format_impl.py defines the .npy format; numpy/lib/_npyio_impl.py defines .npz and load()
    Tested on: source read, not run · checked 2026-10-19; last activity 2026-10-18