File I/O

numpy-ts supports the same file formats as NumPy: .npy (single array), .npz (multiple arrays), and delimited text files. The API is split across two entry points to keep browser bundles free of Node.js dependencies.

Format	Node.js (`numpy-ts/node`)	Browser (`numpy-ts` or `numpy-ts/core`)
`.npy`	`save` / `load`	`serializeNpy` / `parseNpy`
`.npz`	`savez` / `savez_compressed` / `load`	`serializeNpz` / `parseNpz`
Text (CSV, TSV)	`savetxt` / `loadtxt`	`serializeTxt` / `parseTxt`
Text (flexible)	`genfromtxt` / `fromregex`	`genfromtxt` / `fromregex`

Node.js functions read and write files on disk. Browser functions work with ArrayBuffer, Uint8Array, and strings — you handle the network or file access yourself.

NPY files (single array)

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

Node.js
Browser

import { array, save, load } from 'numpy-ts/node';

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/node';

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.

Node.js
Browser

import { array, zeros, savez, savez_compressed, load } from 'numpy-ts/node';

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.

Node.js
Browser

import { array, loadtxt, savetxt } from 'numpy-ts/node';

// 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.

Node.js
Browser

import { genfromtxt } from 'numpy-ts/node';

const data = await genfromtxt('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.

Node.js
Browser

import { fromregex } from 'numpy-ts/node';

// File contents: "Point: x=1.5, y=2.3\nPoint: x=4.0, y=5.1"
const points = await fromregex('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]]

Why a separate Node.js entry point?

File I/O functions that read and write to the filesystem are in numpy-ts/node because they depend on Node.js built-in modules (fs, fs/promises). Keeping them in a separate entry point means that numpy-ts and numpy-ts/core never import fs, so they work cleanly in browsers and edge runtimes without bundler polyfills.If you only need serialization and parsing (not disk access), use serializeNpy, parseNpy, serializeNpz, parseNpz, serializeTxt, and parseTxt from the main entry points.

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/node';

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

Why a separate Node.js entry point?

NumPy compatibility

​NPY files (single array)

​NPZ archives (multiple arrays)

​Text files

​Flexible text loading

​genfromtxt

​fromregex

​Why a separate Node.js entry point?

​NumPy compatibility

NPY files (single array)

NPZ archives (multiple arrays)

Text files

Flexible text loading

genfromtxt

fromregex

Why a separate Node.js entry point?

NumPy compatibility