hesela.devNumPy NPY format
NPY is NumPy's binary format for storing one array with a header describing its data type, shape and storage order.
The numeric payload is interpreted using the header; a digest of payload bytes alone does not bind the array's shape, byte order or coordinate assignment. NPY format versions and NumPy library versions are different identifiers. [1]
Additional dtype metadata is removed during serialization by the reviewed NumPy 2.5.4 implementation, with a warning. An application-supplied unit in dtype.metadata is not a preserved NPY field. [4] [5]
Successive NPY records can share a file object, so an application must define whether it expects exactly one record or a sequence. [3]
NPY does not guarantee preservation of arbitrary ndarray subclass identity, behavior or extra attributes; the ordinary non-pickled array path reconstructs a regular ndarray. This is a documented limitation, separate from the numeric-array observations. [1]
Relations
- related
- NumPy NPZ archive, Checksum, File storage
Limitations
- NPY stores contiguous C- or Fortran-order array data, not an arbitrary in-memory view's strides. [npy-format]
- allow_pickle=False governs object-array loading, not end-to-end integrity or intended scientific meaning. [numpy-load]
- Preserve application semantics such as units and axis identity in an explicit schema bound to the accepted data.
Citations
- NumPy format documentation: NPY and NPZ layout
- NumPy save API: successive array records
- NumPy 2.5.4 pinned format implementation
- NumPy drop_metadata: np.save and np.savez omit additional dtype metadata
Further reading
Sources & caveats
- Format/API documentation and NumPy commit a3d0ef1df045b858e68115001fdabc930bb3b68c.
- Controlled NumPy 2.5.4 / CPython 3.12.3 observations use synthetic numeric arrays and BytesIO, not physical media, mmap or a corruption-rate sample.
- Reproduction: https://hesela.dev/research/npy-interpretation/reproduction.zip