File I/O

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`

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.

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.

File-based (Node / Bun / Deno)
Buffer-based (all environments)

import { array, save, load } 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 load('matrix.npy');
console.log(loaded.shape); // [2, 3]

Synchronous variants are also available:

import { array, saveSync, loadSync } from 'numpy-ts';

const a = array([1, 2, 3]);
saveSync('data.npy', a);
const loaded = loadSync('data.npy');

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:

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.

File-based (Node / Bun / Deno)
Buffer-based (all environments)

import { array, zeros, savez, savez_compressed, load } 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 load('model.npz');
const w = result.arrays.get('weights');
const b = result.arrays.get('biases');

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.

File-based (Node / Bun / Deno)
Buffer-based (all environments)

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',
});

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.

File-based (Node / Bun / Deno)
Buffer-based (all environments)

import { genfromtxtFile } from 'numpy-ts';

const data = await genfromtxtFile('messy_data.csv', {
  delimiter: ',',
  missing_values: ['NA', '', '-'],
  filling_values: 0,
});

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.

File-based (Node / Bun / Deno)
Buffer-based (all environments)

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]]

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:

import type {
  LoadOptions,
  SaveNpzOptions,
  LoadTxtOptions,
  SaveTxtOptions,
} from 'numpy-ts';

Sync I/O internals

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
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
import { load } from 'numpy-ts';

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

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.

numpy-ts

Getting Started

Guides

Resources

NPY files (single array)

NPZ archives (multiple arrays)

Text files

Flexible text loading

genfromtxt

fromregex

Types

Sync I/O internals

NumPy compatibility

​NPY files (single array)

​NPZ archives (multiple arrays)

​Text files

​Flexible text loading

​genfromtxt

​fromregex

​Types

​Sync I/O internals

​NumPy compatibility

NPY files (single array)

NPZ archives (multiple arrays)

Text files

Flexible text loading

genfromtxt

fromregex

Types

Sync I/O internals

NumPy compatibility