npyjs

Read NumPy .npy files in JavaScript (Node, Browser, Deno)

Read .npy arrays saved with NumPy directly in modern JavaScript runtimes.

---

Installation

npm install npyjs
# or
yarn add npyjs

Supports Node ≥18, modern browsers, and Deno/Bun.

---

Import

// Modern named export (recommended)import{load,parse}from"npyjs";// Back-compatibility class (matches legacy docs/tests)importnpyjsfrom"npyjs";

---

Usage

1. Functional API (preferred)

import{load,parse}from"npyjs";constarr=awaitload("my-array.npy");// arr has { data, shape, dtype, fortranOrder }console.log(arr.shape);// e.g., [100, 784]// Parse bytes synchronously when fetching or reading is handled separatelyconstparsed=parse(arrayBuffer);

2. Legacy Class API (still supported)

importnpyjsfrom"npyjs";// Default optionsconstn=newnpyjs();// Disable float16→float32 conversionconstn2=newnpyjs({convertFloat16: false});constarr=awaitn.load("my-array.npy");

---

Accessing multidimensional elements

npyjs returns flat typed arrays with a shape. npyjs also ships a small helper to turn the flat data + shape into nested JS arrays.

import{load}from"npyjs";import{reshape}from"npyjs/reshape";const{ data, shape, fortranOrder }=awaitload("my-array.npy");constnested=reshape(data,shape,fortranOrder);// -> arrays nested by dims

For C-order arrays (the NumPy default), pass fortranOrder = false (default).

For Fortran-order arrays, pass true and the helper will return the natural row-major nested structure.

Or pair it with ndarray or TensorFlow.js:

importndarrayfrom"ndarray";import{load}from"npyjs";const{ data, shape }=awaitload("my-array.npy");consttensor=ndarray(data,shape);console.log(tensor.get(10,15));

---

Supported Data Types

• int8, uint8
• int16, uint16
• int32, uint32
• int64, uint64 (as BigInt)
• float32
• float64
• float16 (converted to float32 by default)
• complex64 (as Float32Array with interleaved real/imag)
• complex128 (as Float64Array with interleaved real/imag)

Float16 Control

// Default: converts float16 → float32constn1=newnpyjs();// Keep raw Uint16Arrayconstn2=newnpyjs({convertFloat16: false});

Complex Numbers

Complex arrays are returned as typed arrays with interleaved real and imaginary parts: [real0, imag0, real1, imag1, ...]

import{load}from"npyjs";const{ data, shape }=awaitload("complex-array.npy");// For a shape of [3], data will have 6 elements: [re0, im0, re1, im1, re2, im2]// Access the first complex numberconstreal0=data[0];constimag0=data[1];

---

Writing .npy Files

Use the dump function to create .npy files:

import{dump}from"npyjs";import{writeFileSync}from"fs";// Dump a typed arrayconstarr=newFloat32Array([1.0,2.0,3.0,4.0]);constbytes=dump(arr,[2,2]);// 2x2 shapewriteFileSync("output.npy",Buffer.from(bytes));// Dump a plain array (dtype is inferred)constplain=[1,2,3,4];constbytes2=dump(plain,[4]);

Dumping Complex Arrays

Since complex types cannot be inferred from plain number arrays, use the dtype option:

import{dump}from"npyjs";// Complex array: 1+2j, 3-4j as interleaved [real, imag, ...]constcomplexData=[1,2,3,-4];constbytes=dump(complexData,[2],{dtype: "c8"});// complex64// Or use c16 for complex128constbytes128=dump(complexData,[2],{dtype: "c16"});

---

Development

• Built with tsup (dual ESM + CJS + d.ts)
• Tested with Vitest
• CI on GitHub Actions (Node 18/20/22)

Commands

npm run build # Build to dist/
npm test# Run Vitest
npm run typecheck # TypeScript type checking

---

License

Apache-2.0 © JHU APL

---

Made with ♥ at

````