transformers.js README

The project's README from github.com/huggingface/transformers.js. As one markdown file: README.md.


transformers.js javascript library logo

NPM NPM Downloads jsDelivr Hits License Documentation

State-of-the-art Machine Learning for the Web

Run 🤗 Transformers directly in your browser, with no need for a server!

Transformers.js is designed to be functionally equivalent to Hugging Face's transformers python library, meaning you can run the same pretrained models using a very similar API. These models support common tasks in different modalities, such as:

Transformers.js uses ONNX Runtime to run models in the browser. The best part about it, is that you can easily convert your pretrained PyTorch, TensorFlow, or JAX models to ONNX using 🤗 Optimum.

For more information, check out the full documentation.

Installation

To install via NPM, run:

npm i @huggingface/transformers

Alternatively, you can use it in vanilla JS, without any bundler, by using a CDN or static hosting. For example, using ES Modules, you can import the library with:

<script type="module">
    import { pipeline } from 'https://cdn.jsdelivr.net/npm/@huggingface/[email protected]';
</script>

Quick tour

It's super simple to translate from existing code! Just like the python library, we support the pipeline API. Pipelines group together a pretrained model with preprocessing of inputs and postprocessing of outputs, making it the easiest way to run models with the library.

Python (original) Javascript (ours) 
from transformers import pipeline

# Allocate a pipeline for sentiment-analysis
pipe = pipeline('sentiment-analysis')

out = pipe('I love transformers!')
# [{'label': 'POSITIVE', 'score': 0.999806941}]

import { pipeline } from '@huggingface/transformers';

// Allocate a pipeline for sentiment-analysis
const pipe = await pipeline('sentiment-analysis');

const out = await pipe('I love transformers!');
// [{'label': 'POSITIVE', 'score': 0.999817686}]

You can also use a different model by specifying the model id or path as the second argument to the pipeline function. For example:

// Use a different model for sentiment-analysis
const pipe = await pipeline('sentiment-analysis', 'Xenova/bert-base-multilingual-uncased-sentiment');

By default, when running in the browser, the model will be run on your CPU (via WASM). If you would like to run the model on your GPU (via WebGPU), you can do this by setting device: 'webgpu', for example:

// Run the model on WebGPU
const pipe = await pipeline('sentiment-analysis', 'Xenova/distilbert-base-uncased-finetuned-sst-2-english', {
  device: 'webgpu',
});

For more information, check out the WebGPU guide.

[!WARNING] The WebGPU API is still experimental in many browsers, so if you run into any issues, please file a bug report.

In resource-constrained environments, such as web browsers, it is advisable to use a quantized version of the model to lower bandwidth and optimize performance. This can be achieved by adjusting the dtype option, which allows you to select the appropriate data type for your model. While the available options may vary depending on the specific model, typical choices include "fp32" (default for WebGPU), "fp16", "q8" (default for WASM), and "q4". For more information, check out the quantization guide.

// Run the model at 4-bit quantization
const pipe = await pipeline('sentiment-analysis', 'Xenova/distilbert-base-uncased-finetuned-sst-2-english', {
  dtype: 'q4',
});

Ready to dive in? Explore our wide variety of demo applications and templates here. You can also launch your own project instantly using the official Transformers.js template on Hugging Face!

Custom usage

By default, Transformers.js uses hosted pretrained models and precompiled WASM binaries, which should work out-of-the-box. You can customize this as follows:

Settings

import { env } from '@huggingface/transformers';

// Specify a custom location for models (defaults to '/models/').
env.localModelPath = '/path/to/models/';

// Disable the loading of remote models from the Hugging Face Hub:
env.allowRemoteModels = false;

// Set location of .wasm files. Defaults to use a CDN.
env.backends.onnx.wasm.wasmPaths = '/path/to/files/';

For a full list of available settings, check out the API Reference.

Convert your models to ONNX

We recommend using Optimum to convert your PyTorch models to ONNX in a single command. For the full list of supported architectures, check out the Optimum documentation.

Supported tasks/models

Here is the list of all tasks and architectures currently supported by Transformers.js. If you don't see your task/model listed here or it is not yet supported, feel free to open a feature request here.

To find compatible models on the Hub, select the "transformers.js" library tag in the filter menu (or visit this link). You can refine your search by selecting the task you're interested in (e.g., text-classification).

Tasks

Natural Language Processing

Task ID Description Supported?
Fill-Mask fill-mask Masking some of the words in a sentence and predicting which words should replace those masks. ✅ (docs)
(models)
Question Answering question-answering Retrieve the answer to a question from a given text. ✅ (docs)
(models)
Sentence Similarity sentence-similarity Determining how similar two texts are. ✅ (docs)
(models)
Summarization summarization Producing a shorter version of a document while preserving its important information. ✅ (docs)
(models)
Table Question Answering table-question-answering Answering a question about information from a given table. ❌
Text Classification text-classification or sentiment-analysis Assigning a label or class to a given text. ✅ (docs)
(models)
Text Generation text-generation Producing new text by predicting the next word in a sequence. ✅ (docs)
(models)
Text-to-text Generation text2text-generation Converting one text sequence into another text sequence. ✅ (docs)
(models)
Token Classification token-classification or ner Assigning a label to each token in a text. ✅ (docs)
(models)
Translation translation Converting text from one language to another. ✅ (docs)
(models)
Zero-Shot Classification zero-shot-classification Classifying text into classes that are unseen during training. ✅ (docs)
(models)
Feature Extraction feature-extraction Transforming raw data into numerical features that can be processed while preserving the information in the original dataset. ✅ (docs)
(models)

Vision

Task ID Description Supported?
Background Removal background-removal Isolating the main subject of an image by removing or making the background transparent. ✅ (docs)
(models)
Depth Estimation depth-estimation Predicting the depth of objects present in an image. ✅ (docs)
(models)
Image Classification image-classification Assigning a label or class to an entire image. ✅ (docs)
(models)
Image Segmentation image-segmentation Divides an image into segments where each pixel is mapped to an object. This task has multiple variants such as instance segmentation, panoptic segmentation and semantic segmentation. ✅ (docs)
(models)
Image-to-Image image-to-image Transforming a source image to match the characteristics of a target image or a target image domain. ✅ (docs)
(models)
Mask Generation mask-generation Generate masks for the objects in an image. ❌
Object Detection object-detection Identify objects of certain defined classes within an image. ✅ (docs)
(models)
Video Classification n/a Assigning a label or class to an entire video. ❌
Unconditional Image Generation n/a Generating images with no condition in any context (like a prompt text or another image). ❌
Image Feature Extraction image-feature-extraction Transforming raw data into numerical features that can be processed while preserving the information in the original image. ✅ (docs)
(models)

Audio

Task ID Description Supported?
Audio Classification audio-classification Assigning a label or class to a given audio. ✅ (docs)
(models)
Audio-to-Audio n/a Generating audio from an input audio source. ❌
Automatic Speech Recognition automatic-speech-recognition Transcribing a given audio into text. ✅ (docs)
(models)
Text-to-Speech text-to-speech or text-to-audio Generating natural-sounding speech given text input. ✅ (docs)
(models)

Tabular

Task ID Description Supported?
Tabular Classification n/a Classifying a target category (a group) based on set of attributes. ❌
Tabular Regression n/a Predicting a numerical value given a set of attributes. ❌

Multimodal

Task ID Description Supported?
Document Question Answering document-question-answering Answering questions on document images. ✅ (docs)
(models)
Image-to-Text image-to-text Output text from a given image. ✅ (docs)
(models)
Text-to-Image text-to-image Generates images from input text. ❌
Visual Question Answering visual-question-answering Answering open-ended questions based on an image. ❌
Zero-Shot Audio Classification `zero-shot-audio-classifi

transformers.js (huggingface/transformers.js)

image-classification
Searching Database…

16.3K ·GitHub
Transformers.js
What is this?Transformers.js lets you run Hugging Face's state-of-the-art machine learning models directly in a web browser, with no server required, using an API designed to mirror the Python transformers library.
Is this a library I import, or a full app?It's a JavaScript library (installable via npm or a CDN), not a standalone app — it's built to be functionally equivalent to Hugging Face's Python transformers library so the same pretrained models can be run with a very similar API.
How do I add it to a project?Install it with npm, or skip bundling entirely and import it as an ES Module straight from a CDN or static hosting for vanilla JS use.
Do I need Python or a backend server to use it?No — models run entirely client-side via ONNX Runtime; by default the library automatically fetches hosted pretrained models and precompiled WASM binaries, so it works out of the box with no server setup.
Can it use my GPU, and does that always work smoothly?GPU acceleration is available via WebGPU by setting device: 'webgpu', but the README flags that the WebGPU API is still experimental in many browsers and may run into issues; by default it falls back to CPU via WASM.
How do I use my own PyTorch or TensorFlow model instead of a model from the Hub?Convert it to ONNX with Hugging Face's Optimum library in a single command, then load it with Transformers.js exactly like any hosted model.
Can I make a model load faster or use less bandwidth in the browser?Yes, set the dtype option (e.g. fp16, q8, q4) to use a quantized version of the model, trading some precision for smaller size and faster inference.
What kinds of tasks can it actually run?It covers NLP (classification, summarization, translation, text generation), vision (classification, object detection, segmentation, depth estimation), audio (speech recognition, text-to-speech) and multimodal tasks like zero-shot classification and embeddings.
Is there a quick way to try it without writing code from scratch?Yes, the README links to a range of demo apps and templates, plus an official Transformers.js project template hosted on Hugging Face you can launch instantly.
What are similar projects?openvino, transformers, DeepLearningExamples, seamless_communication, ncnn, jeeves, tensor2tensor, ludwig
Which topics is it in?jax, image-classification, object-detection, onnx, tensorflow, natural-language-processing, transformers, speech-recognition, text-to-speech, translation, quantization, wasm
Creator
huggingface
Size
121.9 MB
Stars
16.3K
Updated
CommitOct 06Release4.3.1Oct 07
Age
3y
Commits · 90 Days