{
  "schemaVersion": "1.0",
  "canonicalPage": "https://fileformat.co/ext/npz",
  "inspectorUrl": "https://fileformat.co/inspect",
  "spec": {
    "slug": "npz",
    "extension": ".npz",
    "aliases": [],
    "name": "NumPy Zipped Array Archive",
    "shortName": "NPZ",
    "category": "ai-ml",
    "tier": 1,
    "summary": "ZIP container bundling multiple named NumPy `.npy` tensor arrays, widely used for embeddings, calibration datasets, and JAX/MLX checkpoints.",
    "technicalNotes": "Shares PKZIP `50 4B 03 04` magic bytes; disambiguated by inspecting the ZIP Central Directory for `.npy` member entries.",
    "mimeTypes": [
      "application/x-npz",
      "application/zip"
    ],
    "identifiers": {
      "specUrl": "https://numpy.org/doc/stable/reference/generated/numpy.savez.html"
    },
    "binarySignature": {
      "endianness": "little",
      "magicBytes": [
        {
          "offset": 0,
          "hex": "50 4B 03 04",
          "ascii": "PK..",
          "description": "PKZIP Local File Header containing .npy member streams"
        }
      ],
      "containerFamily": "zip",
      "headerLayout": [
        {
          "offset": "0x00 - 0x03",
          "byteOffset": 0,
          "byteLength": 4,
          "lengthLabel": "4 B",
          "dataType": "uint32_le",
          "fieldName": "zip_lfh_sig",
          "description": "PKZIP signature 0x04034B50"
        },
        {
          "offset": "0x08 - 0x09",
          "byteOffset": 8,
          "byteLength": 2,
          "lengthLabel": "2 B",
          "dataType": "uint16_le",
          "fieldName": "compression",
          "description": "0 = Store (np.savez), 8 = Deflate (np.savez_compressed)"
        },
        {
          "offset": "0x1E+",
          "byteOffset": 30,
          "byteLength": 16,
          "lengthLabel": "var",
          "dataType": "utf8",
          "fieldName": "member_name",
          "description": "First array entry name ending in .npy"
        }
      ]
    },
    "securityProfile": {
      "riskLevel": "medium",
      "allowsArbitraryCodeOrMacros": false,
      "xxeRisk": false,
      "polyglotPrependRisk": true,
      "pickleDeserializationRisk": true,
      "uploadValidationNotes": "Always load with np.load(file, allow_pickle=False) and enforce decompression byte quotas on Deflate-compressed .npz uploads."
    },
    "codeSnippets": {
      "python": "import sys, zipfile\nwith zipfile.ZipFile(sys.argv[1], \"r\") as zf:\n    npy_names = [n for n in zf.namelist() if n.endswith(\".npy\")]\n    print(f\"NPZ arrays ({len(npy_names)}): {npy_names}\")",
      "typescript": "export async function isZipHeader(file: File) {\n  const dv = new DataView(await file.slice(0, 4).arrayBuffer());\n  return dv.getUint32(0, true) === 0x04034b50;\n}",
      "rust": "use std::{fs::File, io::Read};\nfn main() -> std::io::Result<()> {\n    let mut b = [0u8; 4];\n    File::open(std::env::args().nth(1).expect(\"usage: <prog> <file>\"))?.read_exact(&mut b)?;\n    println!(\"PKZIP magic: {:02X?}\", b);\n    Ok(())\n}",
      "go": "package main\nimport (\"archive/zip\"; \"fmt\"; \"os\")\nfunc main() {\n    r, err := zip.OpenReader(os.Args[1])\n    if err != nil {\n        fmt.Fprintln(os.Stderr, \"open zip:\", err)\n        os.Exit(1)\n    }\n    defer r.Close()\n    fmt.Printf(\"NPZ entries: %d\\n\", len(r.File))\n}"
    },
    "relatedFormats": [
      "npy",
      "safetensors",
      "pt"
    ],
    "verifiedAt": "2026-11-14T16:09:03Z"
  },
  "samples": [
    {
      "id": "npz-minimal",
      "filename": "minimal-weights.npz",
      "variant": "minimal",
      "title": "Minimal Uncompressed NumPy .npz Archive",
      "description": "Real np.savez output containing weights.npy (4x8 float32) and bias.npy (8 float32).",
      "localPath": "/fixtures/v1/npz/minimal-weights.npz",
      "cdnUrl": "https://fileformat.co/fixtures/v1/npz/minimal-weights.npz",
      "sizeBytes": 668,
      "sha256": "5df985f2575c4c4a1f58f21970bd74830b277688976534283c269be2ccfb2637",
      "expectValid": true
    },
    {
      "id": "npz-realistic",
      "filename": "checkpoint-deflated.npz",
      "variant": "realistic",
      "title": "Deflated Multi-Dtype .npz Checkpoint",
      "description": "Real np.savez_compressed bundle with float32, float64, and int32 arrays.",
      "localPath": "/fixtures/v1/npz/checkpoint-deflated.npz",
      "cdnUrl": "https://fileformat.co/fixtures/v1/npz/checkpoint-deflated.npz",
      "sizeBytes": 1151,
      "sha256": "1da30aadf475322bd6b9df64d90d6fda4f4e600251c6c542bcca7c2a0d8a39ca",
      "expectValid": true
    },
    {
      "id": "npz-edge-case",
      "filename": "truncated-eocd.npz",
      "variant": "edge-case",
      "title": "Truncated EOCD .npz Archive",
      "description": "Valid PK local headers but missing complete EOCD — np.load on the archive must raise.",
      "localPath": "/fixtures/v1/npz/truncated-eocd.npz",
      "cdnUrl": "https://fileformat.co/fixtures/v1/npz/truncated-eocd.npz",
      "sizeBytes": 654,
      "sha256": "3d8d77b9c97b839f497301ec2cbfb8fd34e7c19ae6e0f7ddee51c864c7eb05f5",
      "expectValid": false,
      "edgeCaseTag": "Truncated ZIP EOCD"
    }
  ]
}