A simple format for saving numpy arrays to disk with the full information about them.
.npy format is the standard binary file format in NumPy for persisting a single arbitrary NumPy array on disk. The format stores all of the shape and dtype information necessary to reconstruct the array correctly even on another machine with a different architecture. The format is designed to be as simple as possible while achieving its limited goals.
.npz format is the standard format for persisting multiple NumPy arrays on disk. A
.npz file is a zip file containing multiple
.npy files, one for each array.
.npyfiles that he has been given without much documentation.
Due to limitations in the interpretation of structured dtypes, dtypes with fields with empty names will have the names replaced by ‘f0’, ‘f1’, etc. Such arrays will not round-trip through the format entirely accurately. The data is intact; only the field names will differ. We are working on a fix for this. This fix will not require a change in the file format. The arrays with such structures can still be saved and restored, and the correct dtype may be restored by using the
We recommend using the
.npz extensions for files saved in this format. This is by no means a requirement; applications may wish to use these file formats but use an extension specific to the application. In the absence of an obvious alternative, however, we suggest using
The version numbering of these formats is independent of NumPy version numbering. If the format is upgraded, the code in
numpy.io will still be able to read and write Version 1.0 files.
The first 6 bytes are a magic string: exactly
The next 1 byte is an unsigned byte: the major version number of the file format, e.g.
The next 1 byte is an unsigned byte: the minor version number of the file format, e.g.
\x00. Note: the version of the file format is not tied to the version of the numpy package.
The next 2 bytes form a little-endian unsigned short int: the length of the header data HEADER_LEN.
The next HEADER_LEN bytes form the header data describing the array’s format. It is an ASCII string which contains a Python literal expression of a dictionary. It is terminated by a newline (
\n) and padded with spaces (
\x20) to make the total of
len(magic string) + 2 + len(length) + HEADER_LEN be evenly divisible by 64 for alignment purposes.
The dictionary contains three keys:
“descr” : dtype.descr
numpy.dtypeconstructor to create the array’s dtype.
“fortran_order” : bool
“shape” : tuple of int
For repeatability and readability, the dictionary keys are sorted in alphabetic order. This is for convenience only. A writer SHOULD implement this if possible. A reader MUST NOT depend on this.
Following the header comes the array data. If the dtype contains Python objects (i.e.
dtype.hasobject is True), then the data is a Python pickle of the array. Otherwise the data is the contiguous (either C- or Fortran-, depending on
fortran_order) bytes of the array. Consumers can figure out the number of bytes by multiplying the number of elements given by the shape (noting that
shape=() means there is 1 element) by
The version 1.0 format only allowed the array header to have a total size of 65535 bytes. This can be exceeded by structured arrays with a large number of columns. The version 2.0 format extends the header size to 4 GiB.
numpy.save will automatically save in 2.0 format if the data requires it, else it will always use the more compatible 1.0 format.
The description of the fourth element of the header therefore has become: “The next 4 bytes form a little-endian unsigned int: the length of the header data HEADER_LEN.”
This version replaces the ASCII string (which in practice was latin1) with a utf8-encoded string, so supports structured types with any unicode field names.
.npy format, including motivation for creating it and a comparison of alternatives, is described in the “npy-format” NEP, however details have evolved with time and this document is more current.
© 2005–2019 NumPy Developers
Licensed under the 3-clause BSD License.