Huggingface.js documentation

🤗 Hugging Face Hub API

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

🤗 Hugging Face Hub API

Official utilities to use the Hugging Face Hub API.


pnpm add @huggingface/hub

npm add @huggingface/hub

yarn add @huggingface/hub


import { uploadFiles, listModels } from ""
// or npm:
import { uploadFiles, listModels } from "npm:@huggingface/hub"


For some of the calls, you need to create an account and generate an access token.

Learn how to find free models using the hub package in this interactive tutorial.

import { createRepo, uploadFiles, uploadFilesWithProgress, deleteFile, deleteRepo, listFiles, whoAmI } from "@huggingface/hub";
import type { RepoDesignation, Credentials } from "@huggingface/hub";

const repo: RepoDesignation = { type: "model", name: "myname/some-model" };
const credentials: Credentials = { accessToken: "hf_..." };

const {name: username} = await whoAmI({credentials});

for await (const model of listModels({search: {owner: username}, credentials})) {
  console.log("My model:", model);

await createRepo({ repo, credentials, license: "mit" });

await uploadFiles({
  files: [
    // path + blob content
      path: "file.txt",
      content: new Blob(["Hello World"]),
    // Local file URL
    // Web URL
    new URL(""),
    // Path + Web URL
      path: "myfile.bin",
      content: new URL("")
    // Can also work with native File in browsers

// or

for await (const progressEvent of await uploadFilesWithProgress({
  files: [
})) {

await deleteFile({repo, credentials, path: "myfile.bin"});

await (await downloadFile({ repo, path: "" })).text();

for await (const fileInfo of listFiles({repo})) {

await deleteRepo({ repo, credentials });

OAuth Login

It’s possible to login using OAuth (“Sign in with HF”).

This will allow you get an access token to use some of the API, depending on the scopes set inside the Space or the OAuth App.

import { oauthLoginUrl, oauthHandleRedirectIfPresent } from "@huggingface/hub";

const oauthResult = await oauthHandleRedirectIfPresent();

if (!oauthResult) {
  // If the user is not logged in, redirect to the login page
  window.location.href = await oauthLoginUrl();

// You can use oauthResult.accessToken, oauthResult.accessTokenExpiresAt and oauthResult.userInfo

Checkout the demo:

Performance considerations

When uploading large files, you may want to run the commit calls inside a worker, to offload the sha256 computations.

Remote resources and local files should be passed as URL whenever it’s possible so they can be lazy loaded in chunks to reduce RAM usage. Passing a File inside the browser’s context is fine, because it natively behaves as a Blob.

Under the hood, @huggingface/hub uses a lazy blob implementation to load the file.


  • hash-wasm : Only used in the browser, when committing files over 10 MB. Browsers do not natively support streaming sha256 computations.
  • type-fest : Typings only