Introducing @huggingface/kernels: 200+ WebGPU Kernels for Local AI

2026-09-02 · Hugging Face

Overview

One of the biggest goals of the WebAI team at Hugging Face is to make browser inference as fast and user-friendly as possible. Getting there is a multi-layer effort: models need browser-friendly representations, runtimes need to build efficient execution plans, and the individual GPU operations at the bottom of the stack need to make the most of many different devices and browser implementations.

The team is now releasing the first layer of that effort: @huggingface/kernels, a minimal library for loading and running optimized WebGPU kernels from the Hugging Face Hub, together with an initial collection of 207 kernels at huggingface.co/webgpu-kernels.

The collection covers operations used across a wide variety of machine learning architectures and workloads. More importantly, each kernel is published as a complete, versioned package: its interface, shader templates, correctness cases, benchmark cases, and usage instructions all live together on the Hub.

TL;DR:

  • 207 WebGPU kernels, published as individual repositories in the webgpu-kernels organization, Apache-2.0 licensed.
  • A JavaScript loader, @huggingface/kernels, which downloads, prepares, and runs kernels directly from the Hub.
  • Explicit contracts and reproducible evidence for every kernel, including manifests, correctness tests, benchmark cases, and WGSL shader templates.
  • Fleet, a browser-based benchmarking tool that crowdsources correctness and performance evidence across real-world GPUs.

Why start with kernels?

A model running in the browser eventually becomes a sequence of GPU operations: matrix multiplications, normalizations, convolutions, attention primitives, quantization operations, data-layout transformations, and more. WebGPU makes these operations available across modern browsers through a portable API, while WGSL provides a common language for the shaders that execute them.

Portability, however, does not automatically mean performance. Two shaders can implement the same operation and produce the same output while behaving completely differently across accelerators. Workgroup sizes, memory access patterns, vectorization, data types, and fusion strategies all affect performance, and the best choice can change with the input shape, device, browser, and available WebGPU features.

This is why kernels form a foundational layer of fast browser inference. Higher-level runtimes can only be as efficient as the operations they dispatch. By making those operations individually discoverable, testable, benchmarkable, and versioned, the foundation can be improved independently while keeping a stable contract for the layers above it.

A kernel repository, not just a shader

Each kernel in the collection has its own repository and kernel card. The card documents the operation's semantics, inputs, outputs, attributes, supported data types, source files, and a ready-to-run @huggingface/kernels example.

For example, `ai.onnx.Add` implements elementwise addition with multidirectional broadcasting—one of the simplest operations in a neural network, used everywhere from residual connections to adding a bias. Its card documents the two inputs, the broadcasted output shape, supported data types, and the variants available for different shapes and devices.

Behind the card, the repository contains the artifacts needed to understand and evaluate the implementation:

  • `manifest.json` is the source of truth for the operation contract, defining inputs, outputs, attributes, type constraints, and shape derivation rules.
  • `metadata.json` records the kernel identifier, digests, and provenance.
  • `test.json` contains correctness cases, so an implementation can be checked against expected behavior.
  • `bench.json` contains benchmark and tuning cases that represent the workloads used to evaluate the kernel.
  • `*.wgsl.jinja` files contain the parameterized WGSL implementations used to produce shaders for a particular request and device.

This structure turns a shader into a reusable software artifact. The interface is inspectable without reading WGSL, correctness and performance cases travel with the implementation, and published versions can be loaded explicitly rather than depending on an unversioned file URL. The kernels can also serve as reference implementations for developers building custom WebGPU kernels or integrating these operations into their own runtimes.

Loading a kernel from the Hub

Install the package from npm:


npm install @huggingface/kernels@preview

Running these kernels requires a browser with WebGPU support. WebGPU availability depends on the browser, operating system, GPU, and driver; you can check for it in JavaScript with `"gpu" in navigator`.

@huggingface/kernels provides the bridge between a kernel repository and your application. Call `getKernel` with a Hub repository ID and a contract version, then invoke the returned function with typed input data and tensor shapes. A small bias-add example looks like this:


import { getKernel } from "@huggingface/kernels";
const add = await getKernel("webgpu-kernels/ai.onnx.Add", { version: 1 });

Fleet: crowdsourcing real-world evidence

The team is also launching Fleet, an in-browser GPU benchmarking and testing suite that runs and scores the kernels on your hardware. Beyond the results for your own machine, Fleet gives the community a way to contribute performance and correctness evidence from devices a conventional test lab could never cover. With user consent, every run adds private evidence that can help find failures (incorrect results, pathologically slow cases, and more), improve kernel variants, and make better optimization decisions across real-world hardware.

Source