{
  "schemaVersion": "1.0",
  "canonicalPage": "https://fileformat.co/ext/npy",
  "inspectorUrl": "https://fileformat.co/inspect",
  "spec": {
    "slug": "npy",
    "extension": ".npy",
    "aliases": [],
    "name": "NumPy Array Binary Format",
    "shortName": "NPY",
    "category": "ai-ml",
    "tier": 1,
    "summary": "Simple, mmap-friendly binary representation of a single homogeneous dense tensor with an explicit ASCII header dictionary describing dtype, byte order, and shape.",
    "technicalNotes": "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.",
    "mimeTypes": [
      "application/x-npy",
      "application/octet-stream"
    ],
    "identifiers": {
      "specUrl": "https://numpy.org/doc/stable/reference/generated/numpy.lib.format.html"
    },
    "binarySignature": {
      "endianness": "little",
      "magicBytes": [
        {
          "offset": 0,
          "hex": "93 4E 55 4D 50 59",
          "ascii": ".NUMPY",
          "description": "6-byte NumPy binary magic (0x93 prevents text-mode mangling)"
        }
      ],
      "containerFamily": null,
      "headerLayout": [
        {
          "offset": "0x00 - 0x05",
          "byteOffset": 0,
          "byteLength": 6,
          "lengthLabel": "6 B",
          "dataType": "uint8[6]",
          "fieldName": "magic",
          "description": "0x93 followed by ASCII 'NUMPY'"
        },
        {
          "offset": "0x06 - 0x07",
          "byteOffset": 6,
          "byteLength": 2,
          "lengthLabel": "2 B",
          "dataType": "uint8[2]",
          "fieldName": "version",
          "description": "Major and minor format version (e.g. 1.0)"
        },
        {
          "offset": "0x08 - 0x09",
          "byteOffset": 8,
          "byteLength": 2,
          "lengthLabel": "2 B",
          "dataType": "uint16_le",
          "fieldName": "header_len",
          "description": "Byte length of padded ASCII descriptor dict"
        },
        {
          "offset": "0x0A+",
          "byteOffset": 10,
          "byteLength": 48,
          "lengthLabel": "header_len",
          "dataType": "ascii",
          "fieldName": "header_dict",
          "description": "Literal dict: descr, fortran_order, shape"
        }
      ]
    },
    "securityProfile": {
      "riskLevel": "low",
      "allowsArbitraryCodeOrMacros": false,
      "xxeRisk": false,
      "polyglotPrependRisk": false,
      "pickleDeserializationRisk": true,
      "uploadValidationNotes": "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()."
    },
    "codeSnippets": {
      "python": "import struct, sys\nwith open(sys.argv[1], \"rb\") as f:\n    magic, maj, min_v, hlen = struct.unpack(\"<6sBBH\", f.read(10))\n    assert magic == b\"\\x93NUMPY\"\n    hdr = f.read(hlen).decode(\"latin1\").strip()\n    print(f\"NPY v{maj}.{min_v}: {hdr}\")",
      "typescript": "export async function readNpyHeader(file: File) {\n  const buf = await file.slice(0, 512).arrayBuffer();\n  const dv = new DataView(buf);\n  const hlen = dv.getUint16(8, true);\n  return new TextDecoder('latin1').decode(buf.slice(10, 10 + hlen)).trim();\n}",
      "rust": "use std::{fs::File, io::Read};\nfn main() -> std::io::Result<()> {\n    let mut hdr = [0u8; 10];\n    let mut f = File::open(std::env::args().nth(1).expect(\"usage: <prog> <file>\"))?;\n    f.read_exact(&mut hdr)?;\n    let hlen = u16::from_le_bytes([hdr[8], hdr[9]]) as usize;\n    let mut d = vec![0u8; hlen]; f.read_exact(&mut d)?;\n    println!(\"{}\", String::from_utf8_lossy(&d));\n    Ok(())\n}",
      "go": "package main\nimport (\"encoding/binary\"; \"fmt\"; \"io\"; \"os\")\nfunc main() {\n    f, err := os.Open(os.Args[1])\n    if err != nil {\n        fmt.Fprintln(os.Stderr, \"open:\", err)\n        os.Exit(1)\n    }\n    defer f.Close()\n    h := make([]byte, 10)\n    if _, err := io.ReadFull(f, h); err != nil {\n        fmt.Fprintln(os.Stderr, \"read:\", err)\n        os.Exit(1)\n    }\n    hlen := binary.LittleEndian.Uint16(h[8:10])\n    d := make([]byte, hlen)\n    if _, err := io.ReadFull(f, d); err != nil {\n        fmt.Fprintln(os.Stderr, \"read:\", err)\n        os.Exit(1)\n    }\n    fmt.Println(string(d))\n}"
    },
    "relatedFormats": [
      "npz",
      "safetensors"
    ],
    "verifiedAt": "2026-11-14T16:09:03Z"
  },
  "samples": [
    {
      "id": "npy-minimal",
      "filename": "minimal-f32-4x8.npy",
      "variant": "minimal",
      "title": "Minimal NumPy Float32 (4x8)",
      "description": "Real np.save output: '<f4' descriptor, C-contiguous order, 32 IEEE-754 float32 elements.",
      "localPath": "/fixtures/v1/npy/minimal-f32-4x8.npy",
      "cdnUrl": "https://fileformat.co/fixtures/v1/npy/minimal-f32-4x8.npy",
      "sizeBytes": 256,
      "sha256": "fd4257fe798868b27cf704172e1220473164dad2866b833f7e8fd58060fad063",
      "expectValid": true
    },
    {
      "id": "npy-realistic",
      "filename": "embeddings-f64-8x16.npy",
      "variant": "realistic",
      "title": "Float64 Matrix NumPy (8x16)",
      "description": "Double-precision '<f8' dense embedding matrix written by np.save.",
      "localPath": "/fixtures/v1/npy/embeddings-f64-8x16.npy",
      "cdnUrl": "https://fileformat.co/fixtures/v1/npy/embeddings-f64-8x16.npy",
      "sizeBytes": 1152,
      "sha256": "d4d9449ca4484124d49b8a4d6aab51baf502d3a7b15f26441a38acb20ec4f81f",
      "expectValid": true
    },
    {
      "id": "npy-edge-case",
      "filename": "fortran-nan-truncated.npy",
      "variant": "edge-case",
      "title": "Fortran-Order NaN/Inf Truncated .npy",
      "description": "Real np.save Fortran-order header declaring (32, 32) f4 with payload truncated after 6 floats — np.load must raise.",
      "localPath": "/fixtures/v1/npy/fortran-nan-truncated.npy",
      "cdnUrl": "https://fileformat.co/fixtures/v1/npy/fortran-nan-truncated.npy",
      "sizeBytes": 152,
      "sha256": "2fcb431d32fa5281d8f1e465105e015b209fcb619761b0407fa19adaaa4b35db",
      "expectValid": false,
      "edgeCaseTag": "Fortran Order + NaN/Inf + Truncated"
    }
  ]
}