What Is a .NPZ File?

NumPy Zipped Archive (.npz)

Overview

An .npz file is a ZIP archive containing one or more .npy files, each holding a single NumPy array. It is how NumPy stores several named arrays in one file - a small dataset, a set of model weights, or the mixed inputs and outputs of a computation.

Because the container is a plain ZIP, .npz files are readable by any ZIP tool. Renaming one to .zip and opening it reveals the member arrays as individual .npy files, named after the keyword you saved them under.

Technical Specifications

Format Details

• MIME Type: application/zip
• File Extension: .npz
• Category: Data
• Container: standard ZIP (stored or Deflate-compressed)
• Members: one .npy file per array
• Magic bytes: 50 4B 03 04 (PK\x03\x04)

Identification Caveat

An .npz file is a ZIP file, so signature-based detection sees PK\x03\x04 and will often report it simply as a ZIP archive. Distinguishing an .npz from an ordinary ZIP requires looking inside: if every member ends in .npy and begins with the \x93NUMPY magic, it is a NumPy archive.

This is a good illustration of why container formats are hard to identify. The same applies to NuGet packages, JAR files, and modern Office documents - all ZIP archives wearing different extensions.

File Structure

weights.npz  (ZIP container)
├── layer1_w.npy      \x93NUMPY ... float32, shape (784, 128)
├── layer1_b.npy      \x93NUMPY ... float32, shape (128,)
├── layer2_w.npy      \x93NUMPY ... float32, shape (128, 10)
└── layer2_b.npy      \x93NUMPY ... float32, shape (10,)

Each member is a complete, self-contained .npy file with its own header describing dtype, shape, and memory order. The ZIP directory provides the names.

Arrays saved positionally rather than by keyword get automatic names: arr_0, arr_1, and so on.

Compression

NumPy offers two writers:

• np.savez: stores members uncompressed. Fast to write and read; the file is roughly the sum of the array sizes.
• np.savez_compressed: applies ZIP Deflate to each member. Noticeably slower, but often dramatically smaller for arrays with structure, repeated values, or many zeros.

For dense float data, compression gains are usually modest, because floating-point mantissas look close to random to a general-purpose compressor. For integer labels, masks, sparse matrices, and one-hot encodings, the savings can be very large.

History and Development

.npz arrived alongside .npy as part of NEP 1's tooling in NumPy 1.0.x. The design decision worth noting is the reuse of ZIP rather than the invention of a new container: it made the format immediately inspectable with existing tools, gave optional compression for free, and allowed lazy per-member reads, since ZIP's central directory records where each member starts.

Common Use Cases

• Model checkpoints: saving all weight and bias arrays of a neural network in one file.
• Datasets with splits: bundling X_train, y_train, X_test, and y_test together.
• Multi-output computations: returning several related arrays from a simulation as a single artifact.
• Distributing sample data: shipping test fixtures with a library.
• Sparse matrices: SciPy's save_npz uses this container to store a sparse matrix's component arrays.

How to Open an NPZ File

In Python

import numpy as np

data = np.load("dataset.npz")

# The result is a lazy, dict-like NpzFile
print(data.files)              # ['X_train', 'y_train', 'X_test', 'y_test']

X = data["X_train"]            # decompressed only on access
y = data["y_train"]

data.close()

Using it as a context manager is cleaner, since NpzFile holds an open file handle:

with np.load("dataset.npz") as data:
    X = data["X_train"]
    y = data["y_train"]

Saving

import numpy as np

X_train, y_train = np.random.rand(1000, 20), np.random.randint(0, 2, 1000)

# Named arrays, uncompressed
np.savez("dataset.npz", X_train=X_train, y_train=y_train)

# Named arrays, compressed
np.savez_compressed("dataset.npz", X_train=X_train, y_train=y_train)

With ordinary ZIP tools

# List the arrays without Python
unzip -l dataset.npz

# Extract one array as a standalone .npy
unzip dataset.npz X_train.npy

# Confirm it really is a NumPy archive
unzip -p dataset.npz X_train.npy | head -c 8 | xxd

SciPy sparse matrices

import scipy.sparse as sp

matrix = sp.random(1000, 1000, density=0.01, format="csr")
sp.save_npz("sparse.npz", matrix)
loaded = sp.load_npz("sparse.npz")

Security Considerations

As with .npy, np.load on an .npz containing object-dtype arrays requires allow_pickle=True, which executes pickle deserialisation and can run arbitrary code. The default has been False since NumPy 1.16.3.

There is a second consideration specific to ZIP containers: member names come from the archive, so a maliciously crafted file could in principle carry path-like names. Extract untrusted archives with tools that sanitise paths, and prefer reading arrays through NumPy rather than unpacking to disk.

Advantages

• Multiple named arrays in one file, with meaningful keys.
• Lazy loading: only the members you access are read and decompressed.
• Optional compression: a single argument switch.
• Universally inspectable: any ZIP tool can list and extract members.
• Preserves exact dtypes: each member is a full .npy file.

Limitations

• Ambiguous identification: indistinguishable from other ZIP files by signature alone.
• Compression is per-member: no cross-array redundancy is exploited.
• No partial array reads: you can lazily load a member, but not a slice of one; .npy with mmap_mode is better for that.
• No hierarchy: a flat namespace of names, unlike HDF5's groups.
• Python-centric: readable elsewhere, but rarely a first-class citizen outside the SciPy ecosystem.

Related Formats

• NPY: the single-array format that fills each member.
• ZIP: the underlying container.
• H5: HDF5, the usual choice when you need hierarchy, partial reads, and very large datasets.
• PARQUET: columnar tabular storage with a real schema.
• PICKLE: Python object serialisation for data that is not purely numeric.