Guide · Open source

How to use GPU.js: install and run a GPU kernel in JavaScript

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

GPU.js is an open-source JavaScript library that turns ordinary JavaScript functions into GPU shader code, so they can run in parallel on a graphics card. If no GPU is available, the same functions run as regular JavaScript. This guide shows how to install it, write a kernel, run a matrix multiplication in the browser or Node.js, and know what to watch for before you build on it.

GPU.jsgpujs/gpu.js · ★ 15.5k · MIT Install options & downloads

Quick start

1Install the package. Run npm install gpu.js in your Node.js project. Make sure Node.js is installed first.
2Import GPU. Use const { GPU } = require('gpu.js') in Node, or load dist/gpu-browser.min.js in a web page.
3Create an instance. Call new GPU() to create the instance that builds and runs kernels.
4Write a kernel function. Write a plain JavaScript function that computes one output element, reading this.thread.x and this.thread.y for its position.
5Set the output size. Chain .setOutput([512, 512]) onto createKernel to set the size of the result grid.
6Run the kernel. Call the returned kernel with your input arrays, such as multiplyMatrix(a, b), and read the result.

Install GPU.js with npm

GPU.js is installed as a package with npm. The README's Node instructions use the following command. The README excerpt does not state a required Node.js version, so check the project's documentation for that.

Prerequisite: Node.js
For browsers, you can instead load the built file from dist/gpu-browser.min.js or from a CDN link

npm install gpu.js

Create a GPU instance and a kernel

A kernel is a JavaScript function that computes a single element of the output. You create a GPU instance, pass your function to createKernel, and set the output size with setOutput. Inside the function, this.thread.x and this.thread.y tell the kernel which element it is computing.

The README example multiplies two 512 x 512 matrices. Each output cell is a sum over one row of a and one column of b.

const { GPU } = require('gpu.js');
const gpu = new GPU();
const multiplyMatrix = gpu.createKernel(function(a, b) {
    let sum = 0;
    for (let i = 0; i < 512; i++) {
        sum += a[this.thread.y][i] * b[i][this.thread.x];
    }
    return sum;
}).setOutput([512, 512]);

const c = multiplyMatrix(a, b);

Use GPU.js in the browser

In a web page, load the browser build with a script tag. The README notes that GPU is a constructor and namespace in the browser. The same kernel code works here, as shown in the README's browser example.

The README also lists CDN links for the browser build. These use the @latest tag, so the file you load can change over time.

Local file: dist/gpu-browser.min.js
CDN: unpkg.com/gpu.js@latest/dist/gpu-browser.min.js or cdn.jsdelivr.net/npm/gpu.js@latest/dist/gpu-browser.min.js

<script src="dist/gpu-browser.min.js"></script>
<script>
    const gpu = new GPU();
    const multiplyMatrix = gpu.createKernel(function(a, b) {
        let sum = 0;
        for (let i = 0; i < 512; i++) {
            sum += a[this.thread.y][i] * b[i][this.thread.x];
        }
        return sum;
    }).setOutput([512, 512]);

    const c = multiplyMatrix(a, b);
</script>

Use GPU.js with TypeScript

The README includes a TypeScript version of the same kernel. Parameters are typed as number arrays, and the result is cast to number[][]. The README also links to more TypeScript examples in the project's examples folder.

import { GPU } from 'gpu.js';
const gpu = new GPU();
const multiplyMatrix = gpu.createKernel(function(a: number[][], b: number[][]) {
  let sum = 0;
  for (let i = 0; i < 512; i++) {
    sum += a[this.thread.y][i] * b[i][this.thread.x];
  }
  return sum;
}).setOutput([512, 512]);

const c = multiplyMatrix(a, b) as number[][];

Plan for the v3 async change

The README warns that the next major version will make every kernel call return a Promise, which breaks synchronous code. Async code written with mode 'async' is already in the v3 shape. The README says the WebGL backends keep a synchronous option, setAsyncMode(false), during migration, while WebGPU can never offer one.

If you start a new project, the README's migration steps show the pattern: create the instance with { mode: 'async' } and await each kernel call.

Opt in today with new GPU({ mode: 'async' }) or asyncMode: true per kernel
Use await kernel(a, b) and make the calling function async
For chained kernels, keep pipeline: true and await only the final readback with result.toArray()

const gpu = new GPU({ mode: 'async' });
const kernel = gpu.createKernel(fn).setOutput([512, 512]);
const result = await kernel(a, b);

What people use it for

Multiplying two large matrices in a browser page, as in the README's 512 x 512 example
Running heavy array math in Node.js with the same kernel code
Learning how GPU-style parallel computing works through familiar JavaScript
Building a GPU path in a project that should still run on a CPU when no GPU is available

Frequently asked questions

Is GPU.js free to use?

GPU.js is released under the MIT licence, as listed in the project details. The MIT licence generally allows use, modification and redistribution, so check the licence file in the repository for the full terms.

What do I need to install GPU.js?

The README gives the install command npm install gpu.js and lists Node.js as the prerequisite. It does not state a specific Node.js version, so check the project documentation for that.

Does GPU.js work without a GPU?

Yes. The README says that if a GPU is not available, the functions still run in regular JavaScript. This means the same code can fall back to the CPU.

Does GPU.js work in the browser and Node.js?

Yes. The README shows a browser build loaded with a script tag and a Node example using require('gpu.js'). It also includes a TypeScript example.

Will my GPU.js code break in a future version?

The README warns that v3 will make every kernel call return a Promise, which breaks synchronous code. To prepare, you can use mode 'async' now, since code written that way already matches the v3 contract.

What are the alternatives to GPU.js?

The project's comparison list names TensorFlow.js, Math.js and WebGPU-based compute libraries. GPU.js is focused on turning JavaScript functions into GPU kernels, so pick based on whether you need that or a broader machine learning or math toolkit.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

GPU.js suits JavaScript developers and students who want to run large numeric or matrix work on a GPU with a CPU fallback, and who can accept the planned async change. If you need a stable API for years, need small-data simplicity, or want a GPU framework for non-JavaScript languages, consider a different tool.

Install options & downloads