NPY & NPZ Files

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:

Buffer functions — Work with ArrayBuffer / Uint8Array / strings. Imported from numpy-ts.
File I/O functions — Add file system I/O on top. Also imported from numpy-ts. Works on Node.js, Bun, and Deno. Throws in browser environments.

The numpy-ts/node entry point is deprecated. Imports from it still work but you should migrate to numpy-ts.

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

Name	Type	Default	Description
`buffer`	`ArrayBuffer \| 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

Name	Type	Default	Description
`bytes`	`Uint8Array`	—	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

Name	Type	Default	Description
`bytes`	`Uint8Array`	—	Raw data bytes (after the header).
`metadata`	`NpyMetadata`	—	Metadata from header parsing.

Returns: NDArray — The parsed array.

serializeNpy

Serialize an NDArray to .npy format bytes.

function serializeNpy(arr: NDArray): Uint8Array

Name	Type	Default	Description
`arr`	`NDArray`	—	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

Name	Type	Default	Description
`buffer`	`ArrayBuffer \| Uint8Array`	—	Raw bytes of a `.npz` file.
`options`	`NpzParseOptions`	`{}`	Parse options.

NpzParseOptions:

Name	Type	Default	Description
`force`	`boolean`	`false`	If `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

Name	Type	Default	Description
`arrays`	`NpzArraysInput`	—	Arrays to serialize. Accepts `NDArray[]` (named `arr_0`, `arr_1`, …), `Map<string, NDArray>`, or `Record<string, NDArray>`.
`options`	`NpzSerializeOptions`	`{}`	Serialization options.

NpzSerializeOptions:

Name	Type	Default	Description
`compress`	`boolean`	`false`	Use 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>

Name	Type	Default	Description
`buffer`	`ArrayBuffer \| Uint8Array`	—	Raw bytes of a `.npz` file.
`options`	`NpzParseOptions`	`{}`	Parse options.

Returns: Record<string, NDArray> — Object mapping array names to NDArrays.

File I/O API

Async
Sync

load

Auto-detect file format (.npy or .npz) and load arrays from disk.

function load(path: string, options?: LoadOptions): Promise<NDArray | NpzParseResultNDArray>

Name	Type	Default	Description
`path`	`string`	—	Path to a `.npy` or `.npz` file.
`options`	`LoadOptions`	`undefined`	Loading options.

Returns: Promise<NDArray> for .npy files, Promise<NpzParseResult> for .npz files.

import * as np from 'numpy-ts';

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>

Name	Type	Default	Description
`path`	`string`	—	Output path (should end with `.npy`).
`arr`	`NDArray`	—	Array to save.

Returns: Promise<void>

import * as np from 'numpy-ts';

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

loadNpy

Load a single .npy file from disk. Explicit alternative to the auto-detect load.

function loadNpy(path: string): Promise<NDArray>

Name	Type	Default	Description
`path`	`string`	—	Path to the `.npy` file.

Returns: Promise<NDArray>

import * as np from 'numpy-ts';

const arr = await np.loadNpy('weights.npy');

saveNpy

Save a single NDArray to a .npy file. Explicit alternative to save.

function saveNpy(path: string, arr: NDArray): Promise<void>

Name	Type	Default	Description
`path`	`string`	—	Output path (should end with `.npy`).
`arr`	`NDArray`	—	Array to save.

Returns: Promise<void>

loadNpzFile

Load a .npz file from disk and return parsed arrays.

function loadNpzFile(path: string, options?: LoadOptions): Promise<NpzParseResult>

Name	Type	Default	Description
`path`	`string`	—	Path to the `.npz` file.
`options`	`LoadOptions`	`undefined`	Loading options.

Returns: Promise<NpzParseResult>

import * as np from 'numpy-ts';

const result = await np.loadNpzFile('dataset.npz');

saveNpzFile

Save multiple arrays to a .npz file on disk.

function saveNpzFile(path: string, arrays: NpzArraysInput, options?: SaveNpzOptions): Promise<void>

Name	Type	Default	Description
`path`	`string`	—	Output path. `.npz` extension is appended if missing.
`arrays`	`NpzArraysInput`	—	Named arrays to save. Also accepts `NDArray[]` or `Map`.
`options`	`SaveNpzOptions`	`undefined`	Save options (e.g. compression).

Returns: Promise<void>

savez

Save multiple arrays to an uncompressed .npz file.

function savez(path: string, arrays: NpzArraysInput): Promise<void>

Name	Type	Default	Description
`path`	`string`	—	Output path. `.npz` extension is appended if missing.
`arrays`	`Record<string, NDArray>`	—	Named arrays to save. Also accepts `NDArray[]` or `Map`.

Returns: Promise<void>

import * as np from 'numpy-ts';

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>

Name	Type	Default	Description
`path`	`string`	—	Output path. `.npz` extension is appended if missing.
`arrays`	`Record<string, NDArray>`	—	Named arrays to save.

Returns: Promise<void>

import * as np from 'numpy-ts';

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

Synchronous versions are also available:

import * as np from 'numpy-ts';

// Load
const arr = np.loadSync('weights.npy');
const data = np.loadNpzFileSync('dataset.npz');

// Explicit .npy load/save
const weights = np.loadNpySync('weights.npy');
np.saveNpySync('output.npy', weights);

// Save
np.saveSync('output.npy', arr);
np.saveNpzSync('output.npz', { x: xArr });
np.saveNpzFileSync('output.npz', { x: xArr });

parseNpzSync / loadNpzSync only work with uncompressed .npz files. Use the async versions for compressed files. This is a limitation of the CompressionStream API which is async-only.

Types

LoadOptions

Name	Type	Default	Description
`force`	`boolean`	`false`	If `true`, skip arrays with unsupported dtypes instead of throwing.

SaveNpzOptions

Name	Type	Default	Description
`compress`	`boolean`	`false`	Use DEFLATE compression.

Only the following dtypes are supported: float16, float32, float64, int8, int16, int32, uint8, uint16, uint32, bool, and int64/uint64 (as BigInt). Structured arrays and object dtypes are not supported.

Overview

NDArray

Array Creation

Math

Array Manipulation

Reductions & Statistics

Linear Algebra

Logic & Comparison

Sorting & Searching

Set Operations

Bitwise

Indexing

Gradient & Differences

Polynomials

Random (np.random)

FFT (np.fft)

I/O

Utilities

Browser API

parseNpy

parseNpyHeader

parseNpyData

serializeNpy

parseNpz / parseNpzSync

serializeNpz / serializeNpzSync

loadNpz / loadNpzSync

File I/O API

load

save

loadNpy

saveNpy

loadNpzFile

saveNpzFile

savez

savez_compressed

Types

LoadOptions

SaveNpzOptions

​Browser API

​parseNpy

​parseNpyHeader

​parseNpyData

​serializeNpy

​parseNpz / parseNpzSync

​serializeNpz / serializeNpzSync

​loadNpz / loadNpzSync

​File I/O API

​load

​save

​loadNpy

​saveNpy

​loadNpzFile

​saveNpzFile

​savez

​savez_compressed

​Types

​LoadOptions

​SaveNpzOptions

Browser API

parseNpy

parseNpyHeader

parseNpyData

serializeNpy

parseNpz / parseNpzSync

serializeNpz / serializeNpzSync

loadNpz / loadNpzSync

File I/O API

load

save

loadNpy

saveNpy

loadNpzFile

saveNpzFile

savez

savez_compressed

Types

LoadOptions

SaveNpzOptions