> ## Documentation Index
> Fetch the complete documentation index at: https://numpyts.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# NPY & NPZ Files

> Read and write NumPy's binary .npy and .npz file formats in the browser and Node.js.

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.

> [!WARNING]
>
> 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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
function parseNpyHeader(bytes: Uint8Array): NpyMetadata
```

| Name | Type | Default | Description |
| - | - | - | - |
| `bytes` | `Uint8Array` | -- | Raw bytes of a `.npy` file. |

**Returns:** `NpyMetadata` -- Object with `{ version, header: { descr, fortran_order, shape }, dataOffset }`.

```typescript theme={null}
import * as np from 'numpy-ts';
import { parseNpyHeader, serializeNpy } from 'numpy-ts';

const buffer = serializeNpy(np.zeros([100, 200]));
const meta = parseNpyHeader(buffer);
console.log(meta.header.shape);  // [100, 200]
console.log(meta.header.descr);  // '<f8'
```

***

### parseNpyData

Parse the data portion of a `.npy` file given pre-parsed metadata. Advanced use for custom streaming workflows.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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> }`.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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).

```typescript theme={null}
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

> [tab] Async
>
> ### load
>
> Auto-detect file format (`.npy` or `.npz`) and load arrays from disk.
>
> ```typescript theme={null}
> 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.
>
> ```typescript theme={null}
> 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.
>
> ```typescript theme={null}
> 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>`
>
> ```typescript theme={null}
> 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`.
>
> ```typescript theme={null}
> function loadNpy(path: string): Promise<NDArray>
> ```
>
> | Name | Type | Default | Description |
> | - | - | - | - |
> | `path` | `string` | -- | Path to the `.npy` file. |
>
> **Returns:** `Promise<NDArray>`
>
> ```typescript theme={null}
> 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`.
>
> ```typescript theme={null}
> 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.
>
> ```typescript theme={null}
> function loadNpzFile(path: string, options?: NpzParseOptions): Promise<NpzParseResult>
> ```
>
> | Name | Type | Default | Description |
> | - | - | - | - |
> | `path` | `string` | -- | Path to the `.npz` file. |
> | `options` | `LoadOptions` | `undefined` | Loading options. |
>
> **Returns:** `Promise<NpzParseResult>`
>
> ```typescript theme={null}
> import * as np from 'numpy-ts';
>
> const result = await np.loadNpzFile('dataset.npz');
> ```
>
> ***
>
> ### saveNpzFile
>
> Save multiple arrays to a `.npz` file on disk.
>
> ```typescript theme={null}
> 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.
>
> ```typescript theme={null}
> 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>`
>
> ```typescript theme={null}
> 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.
>
> ```typescript theme={null}
> 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>`
>
> ```typescript theme={null}
> await np.savez_compressed('data.npz', { weights: w, biases: b });
> ```

> [tab] Sync
>
> Every function above has a synchronous counterpart taking the same arguments and returning the value directly rather than a `Promise`. They are Node-only -- they read and write through `node:fs` -- so use the async forms in the browser.
>
> ```typescript theme={null}
> function loadSync(path: string, options?: LoadOptions): NDArray | NpzParseResultNDArray
>
> function loadNpySync(path: string): NDArray
>
> function loadNpzFileSync(path: string, options?: NpzParseOptions): NpzParseResultNDArray
>
> function saveSync(path: string, arr: NDArray): void
>
> function saveNpySync(path: string, arr: NDArray): void
>
> function saveNpzFileSync(path: string, arrays: NpzArraysInput): void
> ```
>
> > [!NOTE]
> >
> > `saveNpzFileSync` takes no options argument. Compression is only available through async `saveNpzFile`, for the reason given below.
>
> Usage:
>
> ```typescript theme={null}
> import * as np from 'numpy-ts';
>
> // Load
> const arr = np.loadNpySync('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.saveNpzFileSync('output.npz', { x: arr });
> ```
>
> > [!TIP]
> >
> > `parseNpzSync` / `loadNpzSync` only work with uncompressed `.npz` files. Use the async versions for compressed files. This is a limitation of the [`CompressionStream API`](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream) 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. |

***

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.