Skip to main content
numpy-ts provides full support for NumPy’s .npy (single array) and .npz (multiple arrays, ZIP archive) binary formats. The API is split into two layers:
  • Browser functions — Work with ArrayBuffer / Uint8Array / strings. Imported from numpy-ts or numpy-ts/core.
  • Node.js functions — Add file system I/O on top. Imported from numpy-ts/node.

​
Browser API

These functions work in any JavaScript environment (browser, Deno, Bun, Node.js) since they operate on bytes, not files.

​
parseNpy

Parse a .npy buffer into an NDArray. 
function parseNpy(buffer: ArrayBuffer | Uint8Array): NDArray
NameTypeDefaultDescription
bufferArrayBuffer | Uint8Array—Raw bytes of a .npy file.
Returns: NDArray — The parsed array with correct shape, dtype, and data. 
import { parseNpy } from 'numpy-ts';

const response = await fetch('/data/weights.npy');
const buffer = await response.arrayBuffer();
const arr = parseNpy(buffer);
console.log(arr.shape, arr.dtype);

​
parseNpyHeader

Parse only the header of a .npy file without reading the data. Useful for inspecting file metadata. 
function parseNpyHeader(bytes: Uint8Array): NpyMetadata
NameTypeDefaultDescription
bytesUint8Array—Raw bytes of a .npy file.
Returns: NpyHeader — Object with { descr, fortran_order, shape, version, headerLength }. 
import { parseNpyHeader } from 'numpy-ts';

const header = parseNpyHeader(buffer);
console.log(header.shape);  // e.g. [100, 200]
console.log(header.descr);  // e.g. '<f8'

​
parseNpyData

Parse the data portion of a .npy file given pre-parsed metadata. Advanced use for custom streaming workflows. 
function parseNpyData(bytes: Uint8Array, metadata: NpyMetadataType): NDArray
NameTypeDefaultDescription
bytesUint8Array—Raw data bytes (after the header).
metadataNpyMetadata—Metadata from header parsing.
Returns: NDArray — The parsed array.

​
serializeNpy

Serialize an NDArray to .npy format bytes. 
function serializeNpy(arr: NDArray): Uint8Array
NameTypeDefaultDescription
arrNDArray—The array to serialize.
Returns: Uint8Array — The .npy file as bytes, ready to be written or downloaded. 
import * as np from 'numpy-ts';
import { serializeNpy } from 'numpy-ts';

const arr = np.array([[1, 2, 3], [4, 5, 6]]);
const bytes = serializeNpy(arr);

// Download in browser
const blob = new Blob([bytes], { type: 'application/octet-stream' });

​
parseNpz / parseNpzSync

Parse a .npz buffer into a collection of named arrays. The async version supports DEFLATE-compressed files. 
function parseNpz(
  buffer: ArrayBuffer | Uint8Array,
  options?: NpzParseOptions
): Promise<NpzParseResult>

function parseNpzSync(
  buffer: ArrayBuffer | Uint8Array,
  options?: NpzParseOptions
): NpzParseResult
NameTypeDefaultDescription
bufferArrayBuffer | Uint8Array—Raw bytes of a .npz file.
optionsNpzParseOptions{}Parse options.
NpzParseOptions:
NameTypeDefaultDescription
forcebooleanfalseIf true, skip arrays with unsupported dtypes instead of throwing.
Returns: NpzParseResult — { arrays: Map<string, NDArray>, skipped: string[], errors: Map<string, string> }. 
import { parseNpz } from 'numpy-ts';

const response = await fetch('/data/model.npz');
const buffer = await response.arrayBuffer();
const result = await parseNpz(buffer);

for (const [name, arr] of result.arrays) {
  console.log(name, arr.shape);
}

​
serializeNpz / serializeNpzSync

Serialize multiple arrays to .npz format. The async version supports DEFLATE compression. 
function serializeNpz(
  arrays: NpzArraysInput,
  options?: NpzSerializeOptions
): Promise<Uint8Array>

function serializeNpzSync(
  arrays: NpzArraysInput
): Uint8Array
NameTypeDefaultDescription
arraysNpzArraysInput—Arrays to serialize. Accepts NDArray[] (named arr_0, arr_1, …), Map<string, NDArray>, or Record<string, NDArray>.
optionsNpzSerializeOptions{}Serialization options.
NpzSerializeOptions:
NameTypeDefaultDescription
compressbooleanfalseUse DEFLATE compression (like np.savez_compressed).
Returns: Uint8Array (or Promise<Uint8Array>) — The .npz file as bytes. 
import * as np from 'numpy-ts';
import { serializeNpz } from 'numpy-ts';

const x = np.array([1, 2, 3]);
const y = np.array([4, 5, 6]);
const bytes = await serializeNpz({ x, y });

​
loadNpz / loadNpzSync

Convenience wrappers that parse an .npz buffer and return a simple Record<string, NDArray> (discarding error/skip metadata). 
function loadNpz(
  buffer: ArrayBuffer | Uint8Array,
  options?: NpzParseOptions
): Promise<Record<string, NDArray>>

function loadNpzSync(
  buffer: ArrayBuffer | Uint8Array,
  options?: NpzParseOptions
): Record<string, NDArray>
NameTypeDefaultDescription
bufferArrayBuffer | Uint8Array—Raw bytes of a .npz file.
optionsNpzParseOptions{}Parse options.
Returns: Record<string, NDArray> — Object mapping array names to NDArrays.

​
Node.js API

​
load

Auto-detect file format (.npy or .npz) and load arrays from disk.
function load(path: string, options?: LoadOptions): Promise<NDArray | NpzParseResultNDArray>
NameTypeDefaultDescription
pathstring—Path to a .npy or .npz file.
optionsLoadOptionsundefinedLoading options.
Returns: Promise<NDArray> for .npy files, Promise<NpzParseResult> for .npz files.
import * as np from 'numpy-ts/node';

const arr = await np.load('weights.npy');
const data = await np.load('dataset.npz');

​
save

Save a single NDArray to a .npy file.
function save(path: string, arr: NDArray): Promise<void>
NameTypeDefaultDescription
pathstring—Output path (should end with .npy).
arrNDArray—Array to save.
Returns: Promise<void>
import * as np from 'numpy-ts/node';

const arr = np.array([[1, 2], [3, 4]]);
await np.save('matrix.npy', arr);

​
savez

Save multiple arrays to an uncompressed .npz file.
function savez(path: string, arrays: NpzArraysInput): Promise<void>
NameTypeDefaultDescription
pathstring—Output path. .npz extension is appended if missing.
arraysRecord<string, NDArray>—Named arrays to save. Also accepts NDArray[] or Map.
Returns: Promise<void>
import * as np from 'numpy-ts/node';

await np.savez('data.npz', { x: xArr, y: yArr });

​
savez_compressed

Save multiple arrays to a DEFLATE-compressed .npz file.
function savez_compressed(path: string, arrays: NpzArraysInput): Promise<void>
NameTypeDefaultDescription
pathstring—Output path. .npz extension is appended if missing.
arraysRecord<string, NDArray>—Named arrays to save.
Returns: Promise<void>
import * as np from 'numpy-ts/node';

await np.savez_compressed('data.npz', { weights: w, biases: b });