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

# File I/O

> Save and load arrays in .npy, .npz, and text formats. File-based I/O works on Node.js, Bun, and Deno; buffer-based I/O works everywhere including browsers.

numpy-ts supports the same file formats as NumPy: `.npy` (single array), `.npz` (multiple arrays), and delimited text files. All functions are available from the main `numpy-ts` entry point.

| Category | File-based (Node / Bun / Deno) | Buffer-based (all environments) |
| - | - | - |
| `.npy` | `loadNpy` / `loadNpySync` / `saveNpy` / `saveNpySync` | `serializeNpy` / `parseNpy` |
| `.npz` | `loadNpzFile` / `loadNpzFileSync` / `saveNpzFile` / `saveNpzFileSync` / `savez` / `savez_compressed` | `serializeNpz` / `parseNpz` |
| Auto-detect | `load` / `loadSync` / `save` / `saveSync` | -- |
| Text (CSV, TSV) | `loadtxt` / `loadtxtSync` / `savetxt` / `savetxtSync` | `serializeTxt` / `parseTxt` |
| Text (flexible) | `genfromtxtFile` / `genfromtxtFileSync` / `fromregexFile` / `fromregexFileSync` | `genfromtxt` / `fromregex` |

> [!NOTE]
>
> File-based functions read and write files on disk and require a server runtime (Node.js, Bun, or Deno). In the browser, they throw: *"File IO requires Node.js, Bun, or Deno. In the browser, use parseNpy(buffer) / parseTxt(text) with fetch() instead."* Buffer-based functions work with `ArrayBuffer`, `Uint8Array`, and strings in all environments.

> [!TIP]
>
> `numpy-ts/node` still works but is a **deprecated** alias for `numpy-ts`. Update your imports to `from 'numpy-ts'`.

## NPY files (single array)

The `.npy` format stores a single array with its dtype and shape metadata.

> [tab] File-based (Node / Bun / Deno)
>
> ```typescript theme={null}
> import { array, save, loadNpy } from 'numpy-ts';
>
> const a = array([[1, 2, 3], [4, 5, 6]]);
>
> // Save to disk
> await save('matrix.npy', a);
>
> // Load from disk
> const loaded = await loadNpy('matrix.npy');
> console.log(loaded.shape); // [2, 3]
> ```
>
> Synchronous variants are also available:
>
> ```typescript theme={null}
> import { array, saveSync, loadSync } from 'numpy-ts';
>
> const a = array([1, 2, 3]);
> saveSync('data.npy', a);
> const loaded = loadSync('data.npy');
> ```

> [tab] Buffer-based (all environments)
>
> ```typescript theme={null}
> import { array, serializeNpy, parseNpy } from 'numpy-ts';
>
> const a = array([[1, 2, 3], [4, 5, 6]]);
>
> // Serialize to Uint8Array
> const bytes = serializeNpy(a);
>
> // Parse from ArrayBuffer (e.g., from fetch)
> const response = await fetch('https://example.com/matrix.npy');
> const buffer = await response.arrayBuffer();
> const loaded = parseNpy(buffer);
> console.log(loaded.shape); // [2, 3]
> ```
>
> You can also use the core entry point for smaller bundles:
>
> ```typescript theme={null}
> import { array, serializeNpy, parseNpy } from 'numpy-ts/core';
> ```

## NPZ archives (multiple arrays)

The `.npz` format stores multiple named arrays in a single ZIP archive. `savez_compressed` applies deflate compression.

> [tab] File-based (Node / Bun / Deno)
>
> ```typescript theme={null}
> import { array, zeros, savez, savez_compressed, loadNpzFile } from 'numpy-ts';
>
> const weights = array([[0.1, 0.2], [0.3, 0.4]]);
> const biases = zeros([2]);
>
> // Save multiple arrays (uncompressed)
> await savez('model.npz', { weights, biases });
>
> // Save with compression
> await savez_compressed('model_compressed.npz', { weights, biases });
>
> // Load returns an object with a Map of arrays
> const result = await loadNpzFile('model.npz');
> const w = result.arrays.get('weights');
> const b = result.arrays.get('biases');
> ```

> [tab] Buffer-based (all environments)
>
> ```typescript theme={null}
> import { array, zeros, serializeNpz, parseNpz } from 'numpy-ts';
>
> const weights = array([[0.1, 0.2], [0.3, 0.4]]);
> const biases = zeros([2]);
>
> // Serialize to Uint8Array
> const bytes = await serializeNpz({ weights, biases });
>
> // Parse from ArrayBuffer (e.g., from fetch)
> const response = await fetch('https://example.com/model.npz');
> const buffer = await response.arrayBuffer();
> const result = await parseNpz(buffer);
> const w = result.arrays.get('weights');
> const b = result.arrays.get('biases');
> ```

## Text files

Load and save delimited text files such as CSV and TSV.

> [tab] File-based (Node / Bun / Deno)
>
> ```typescript theme={null}
> import { array, loadtxt, savetxt } from 'numpy-ts';
>
> // Load a CSV file
> const data = await loadtxt('data.csv', { delimiter: ',' });
>
> // Load with options
> const filtered = await loadtxt('data.csv', {
>   delimiter: ',',
>   skiprows: 1,         // Skip header row
>   usecols: [0, 2],     // Only columns 0 and 2
> });
>
> // Save as CSV
> const a = array([[1.1, 2.2], [3.3, 4.4]]);
> await savetxt('output.csv', a, {
>   delimiter: ',',
>   header: 'x,y',
>   fmt: '%.2f',
> });
> ```

> [tab] Buffer-based (all environments)
>
> ```typescript theme={null}
> import { array, parseTxt, serializeTxt } from 'numpy-ts';
>
> // Parse from a string (e.g., from fetch or FileReader)
> const csv = `1.0,2.0,3.0
> 4.0,5.0,6.0`;
> const data = parseTxt(csv, { delimiter: ',' });
> console.log(data.shape); // [2, 3]
>
> // Serialize to a string
> const a = array([[1.1, 2.2], [3.3, 4.4]]);
> const text = serializeTxt(a, {
>   delimiter: ',',
>   header: 'x,y',
>   fmt: '%.2f',
> });
> console.log(text);
> // # x,y
> // 1.10,2.20
> // 3.30,4.40
> ```

## Flexible text loading

### genfromtxt

Like `loadtxt`, but handles missing values more gracefully.

> [tab] File-based (Node / Bun / Deno)
>
> ```typescript theme={null}
> import { genfromtxtFile } from 'numpy-ts';
>
> const data = await genfromtxtFile('messy_data.csv', {
>   delimiter: ',',
>   missing_values: ['NA', '', '-'],
>   filling_values: 0,
> });
> ```

> [tab] Buffer-based (all environments)
>
> ```typescript theme={null}
> import { genfromtxt } from 'numpy-ts';
>
> const csv = `1.0,2.0,3.0
> 4.0,NA,6.0
> 7.0,8.0,`;
>
> const data = genfromtxt(csv, {
>   delimiter: ',',
>   missing_values: ['NA', ''],
>   filling_values: 0,
> });
> // [[1, 2, 3], [4, 0, 6], [7, 8, 0]]
> ```

### fromregex

Extract numeric data from unstructured text using regular expressions.

> [tab] File-based (Node / Bun / Deno)
>
> ```typescript theme={null}
> import { fromregexFile } from 'numpy-ts';
>
> // File contents: "Point: x=1.5, y=2.3\nPoint: x=4.0, y=5.1"
> const points = await fromregexFile('points.txt', /x=([\d.]+), y=([\d.]+)/);
> console.log(points.shape); // [2, 2]
> console.log(points.toArray()); // [[1.5, 2.3], [4.0, 5.1]]
> ```

> [tab] Buffer-based (all environments)
>
> ```typescript theme={null}
> import { fromregex } from 'numpy-ts';
>
> const text = `Point: x=1.5, y=2.3
> Point: x=4.0, y=5.1`;
>
> const points = fromregex(text, /x=([\d.]+), y=([\d.]+)/);
> console.log(points.toArray()); // [[1.5, 2.3], [4.0, 5.1]]
> ```

## Types

File I/O functions accept typed options objects:

```typescript theme={null}
import type {
  LoadOptions,
  SaveNpzOptions,
  LoadTxtOptions,
  SaveTxtOptions,
} from 'numpy-ts';
```

## Sync I/O internals

> [!TIP]
>
> Sync file I/O functions (`loadSync`, `saveSync`, `loadNpySync`, etc.) use an async self-warming cache that resolves `node:fs` at module load time. This is transparent in practice. In the extremely unlikely case that you call a sync function before the microtask queue has flushed, call any async I/O function first to ensure the cache is ready.

## NumPy compatibility

Files saved by numpy-ts can be loaded by Python NumPy, and vice versa:

```python theme={null}
# Python
import numpy as np

# Load a file saved by numpy-ts
arr = np.load('matrix.npy')

# Save a file for numpy-ts to load
np.save('from_python.npy', np.array([[1, 2], [3, 4]]))
```

```typescript theme={null}
// TypeScript
import { loadNpy } from 'numpy-ts';

const arr = await loadNpy('from_python.npy');
console.log(arr.toArray()); // [[1, 2], [3, 4]]
```

> [!WARNING]
>
> numpy-ts does not support NumPy object arrays, structured arrays, or pickle-based `.npy` files. Only numeric dtypes (`float16`, `float64`, `float32`, `int32`, `int16`, `int8`, `uint32`, `uint16`, `uint8`, `bool`, `complex128`, `complex64`) are supported.


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