.npy Tier 1 · Deep AST Parser

NumPy Array Binary Format

Simple, mmap-friendly binary representation of a single homogeneous dense tensor with an explicit ASCII header dictionary describing dtype, byte order, and shape.

Starts with `\x93NUMPY`, major/minor bytes, header length (uint16_le in v1.0, uint32_le in v2.0+), and a space-padded Python literal dict aligned to 64 bytes.

MIME Types application/x-npy, application/octet-stream

Byte Endianness little

Canonical Spec Official Specification ↗

0xFF

Drop any .npy file (even 100 GB+) to inspect locally

Reads tiny File.slice() header/footer pages in a sandboxed Web Worker · 0 Bytes Uploaded

Binary Signature & Wire Layout

.npy Magic Bytes & Header Offset Map

Offset: 0x00 (0 B) ASCII: .NUMPY

93 4E 55 4D 50 59

6-byte NumPy binary magic (0x93 prevents text-mode mangling)

Byte Offset	Length	Data Type	Field Name	Engineering Description
0x00 - 0x05	6 B	uint8[6]	magic	0x93 followed by ASCII 'NUMPY'
0x06 - 0x07	2 B	uint8[2]	version	Major and minor format version (e.g. 1.0)
0x08 - 0x09	2 B	uint16_le	header_len	Byte length of padded ASCII descriptor dict
0x0A+	header_len	ascii	header_dict	Literal dict: descr, fortran_order, shape

Upload Gateway & AppSec Advisory

.npy Security & Polyglot Risk Matrix

Risk Level: low

Arbitrary Code / Macros

NO (Inert Data)

Pickle Deserialization

HIGH RISK (Arbitrary Exec)

XML External Entity (XXE)

NONE

Polyglot Prepend Risk

LOW (Strict 0x00 Magic)

Backend Upload Validation Recommendation

Reject files whose header_dict declares dtype '|O' (Python object array), which invokes pickle.load(). Parse header_dict with a strict regex/AST rather than eval().

Compiler-Verified Reference Code

Read .npy Header & Metadata Without Heavy Dependencies

✓ Zero-Dependency .npy Header Reader

import struct, sys
with open(sys.argv[1], "rb") as f:
    magic, maj, min_v, hlen = struct.unpack("<6sBBH", f.read(10))
    assert magic == b"\x93NUMPY"
    hdr = f.read(hlen).decode("latin1").strip()
    print(f"NPY v{maj}.{min_v}: {hdr}")

CI/CD & Unit Test Fixtures

Deterministic .npy Sample Files & Edge Cases

Open Full .npy Sample Matrix & Mutator →

minimalexpect: valid

minimal-f32-4x8.npy

Real np.save output: '<f4' descriptor, C-contiguous order, 32 IEEE-754 float32 elements.

↓ Download (256 B)

SHA-256: fd4257fe798868b27cf704172e1220473164dad2866b833f7e8fd58060fad063

Exact: 256 bytes

curl -fsSL https://fileformat.co/fixtures/v1/npy/minimal-f32-4x8.npy -o minimal-f32-4x8.npy \
  && echo "fd4257fe798868b27cf704172e1220473164dad2866b833f7e8fd58060fad063  minimal-f32-4x8.npy" | shasum -a 256 -c

realisticexpect: valid

embeddings-f64-8x16.npy

Double-precision '<f8' dense embedding matrix written by np.save.

↓ Download (1.1 KB)

SHA-256: d4d9449ca4484124d49b8a4d6aab51baf502d3a7b15f26441a38acb20ec4f81f

Exact: 1,152 bytes

curl -fsSL https://fileformat.co/fixtures/v1/npy/embeddings-f64-8x16.npy -o embeddings-f64-8x16.npy \
  && echo "d4d9449ca4484124d49b8a4d6aab51baf502d3a7b15f26441a38acb20ec4f81f  embeddings-f64-8x16.npy" | shasum -a 256 -c

edge-caseFortran Order + NaN/Inf + Truncatedexpect: parser_error

fortran-nan-truncated.npy

Real np.save Fortran-order header declaring (32, 32) f4 with payload truncated after 6 floats — np.load must raise.

↓ Download (152 B)

SHA-256: 2fcb431d32fa5281d8f1e465105e015b209fcb619761b0407fa19adaaa4b35db

Exact: 152 bytes

curl -fsSL https://fileformat.co/fixtures/v1/npy/fortran-nan-truncated.npy -o fortran-nan-truncated.npy \
  && echo "2fcb431d32fa5281d8f1e465105e015b209fcb619761b0407fa19adaaa4b35db  fortran-nan-truncated.npy" | shasum -a 256 -c

Related Specifications & Alternatives

.npz little

NPZ

ZIP container bundling multiple named NumPy `.npy` tensor arrays, widely used for embeddings, calibration datasets, and JAX/MLX checkpoints.

.safetensors little

SafeTensors

Hugging Face's memory-safe, zero-copy tensor serialization format designed to replace Pickle-based PyTorch checkpoints without arbitrary code execution risks.