# @huggingface/hub

> Utilities to interact with the Hugging Face hub

Latest version **2.17.10** (published 2026-10-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install @huggingface/hub
pnpm add @huggingface/hub
yarn add @huggingface/hub
bun add @huggingface/hub
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.17.10 |
| Published | 2026-10-28 |
| First published | 2023-02-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2600 |
| Author | Hugging Face |
| Maintainers | julien-c, pierric, coyotte508, xenova, gary149 |
| Keywords | api, client, face, hub, hugging, huggingface |

## Links

- npm: https://www.npmjs.com/package/@huggingface/hub
- Repository: https://github.com/huggingface/huggingface.js
- Homepage: https://github.com/huggingface/huggingface.js#readme
- Issues: https://github.com/huggingface/huggingface.js/issues
- npm.io page: https://npm.io/package/@huggingface/hub

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 2.17.10 (latest) — 2026-10-28
- 2.15.0-parallel-dl.4 (parallel-dl) — 2026-08-06
- 2.17.9 — 2026-10-22
- 2.17.8 — 2026-10-15
- 2.17.7 — 2026-10-14
- 2.17.6 — 2026-10-08
- 2.17.5 — 2026-09-22
- 2.17.4 — 2026-09-20
- 2.17.3 — 2026-09-18
- 2.17.2 — 2026-09-15
- 2.17.1 — 2026-09-10
- 2.17.0 — 2026-09-07
- 2.16.3 — 2026-09-02
- 2.16.2 — 2026-09-02
- 2.16.1 — 2026-08-28
- … 168 more at https://npm.io/package/@huggingface/hub/versions

## README

# 🤗 Hugging Face Hub API

Official utilities to use the Hugging Face Hub API.

## Install

```console
pnpm add @huggingface/hub

npm add @huggingface/hub

yarn add @huggingface/hub
```

### Deno

```ts
// esm.sh
import { uploadFiles, listModels } from "https://esm.sh/@huggingface/hub"
// or npm:
import { uploadFiles, listModels } from "npm:@huggingface/hub"
```

Check out the [full documentation](https://huggingface.co/docs/huggingface.js/hub/README).

## Usage

For some of the calls, you need to create an account and generate an [access token](https://huggingface.co/settings/tokens).

Learn how to find free models using the hub package in this [interactive tutorial](https://scrimba.com/scrim/c7BbVPcd?pl=pkVnrP7uP).

```ts
import * as hub from "@huggingface/hub";
import type { RepoDesignation } from "@huggingface/hub";

const repo: RepoDesignation = { type: "model", name: "myname/some-model" };

const {name: username} = await hub.whoAmI({accessToken: "hf_..."});

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

const specificModel = await hub.modelInfo({name: "openai-community/gpt2"});
await hub.checkRepoAccess({repo, accessToken: "hf_..."});

await hub.createRepo({ repo, accessToken: "hf_...", license: "mit" });

await hub.uploadFiles({
  repo,
  accessToken: "hf_...",
  files: [
    // path + blob content
    {
      path: "file.txt",
      content: new Blob(["Hello World"]),
    },
    // Local file URL
    pathToFileURL("./pytorch-model.bin"),
    // Local folder URL
    pathToFileURL("./models"),
    // Web URL
    new URL("https://huggingface.co/xlm-roberta-base/resolve/main/tokenizer.json"),
    // Path + Web URL
    {
      path: "myfile.bin",
      content: new URL("https://huggingface.co/bert-base-uncased/resolve/main/pytorch_model.bin")
    }
    // Can also work with native File in browsers
  ],
});

// or

for await (const progressEvent of await hub.uploadFilesWithProgress({
  repo,
  accessToken: "hf_...",
  files: [
    ...
  ],
})) {
  console.log(progressEvent);
}

// Edit a file in place, without downloading/uploading its unchanged data
const file = await hub.downloadFile({ repo, path: "myfile.bin", accessToken: "hf_..." });
await hub.uploadFile({
  repo,
  accessToken: "hf_...",
  file: {
    path: "myfile.bin",
    originalContent: file,
    edits: [{
      // Replace bytes [0, 4)
      start: 0,
      end: 4,
      content: new Blob(["new prefix"])
    }, {
      // Append at the end
      start: file.size,
      end: file.size,
      content: new Blob(["suffix"])
    }]
  }
});

await hub.deleteFile({repo, accessToken: "hf_...", path: "myfile.bin"});

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

for await (const fileInfo of hub.listFiles({repo})) {
  console.log(fileInfo);
}

await hub.deleteRepo({ repo, accessToken: "hf_..." });
```

### Buckets

[Storage Buckets](https://huggingface.co/docs/hub/storage-buckets) are mutable, non-versioned storage on the Hub. Use a `buckets/` prefix (or `{ type: "bucket", name }`) with the same functions:

```ts
const bucket = "buckets/myname/my-bucket";

await hub.createRepo({ repo: bucket, accessToken: "hf_..." });

await hub.uploadFiles({ repo: bucket, accessToken: "hf_...", files: [pathToFileURL("./checkpoints")] });

for await (const fileInfo of hub.listFiles({ repo: bucket, recursive: true, accessToken: "hf_..." })) {
  console.log(fileInfo.path, fileInfo.uploadedAt);
}

// Copy files from a model or dataset repo into a bucket server-side, without downloading them
await hub.copyFolder({
  source: { repo: { type: "dataset", name: "myname/my-dataset" }, path: "data" },
  destination: { repo: bucket, path: "data" },
  accessToken: "hf_...",
});
```

## CLI usage

You can use `@huggingface/hub` in CLI mode to upload and download files and folders to/from your repo.

```console
npx @huggingface/hub upload coyotte508/test-model .
npx @huggingface/hub upload datasets/coyotte508/test-dataset .
# Same thing
npx @huggingface/hub upload --repo-type dataset coyotte508/test-dataset .
# Upload new data with 0 history in a separate branch
npx @huggingface/hub branch create coyotte508/test-model release --empty
npx @huggingface/hub upload coyotte508/test-model . --revision release

# Download files to the current directory (or --local-dir)
npx @huggingface/hub download coyotte508/test-model config.json
npx @huggingface/hub download coyotte508/test-model config.json README.md --local-dir ./test-model
# Download an entire repo, optionally filtered with --include / --exclude
npx @huggingface/hub download coyotte508/test-model --local-dir ./test-model
npx @huggingface/hub download --repo-type dataset coyotte508/test-dataset --include "*.json"

npx @huggingface/hub --help
npx @huggingface/hub upload --help
npx @huggingface/hub download --help
```

You can also install globally with `npm install -g @huggingface/hub`. Then you can do:

```console
hfjs upload coyotte508/test-model .

hfjs branch create --repo-type dataset coyotte508/test-dataset release --empty
hfjs upload --repo-type dataset coyotte508/test-dataset . --revision release

hfjs download coyotte508/test-model config.json
hfjs download coyotte508/test-model --local-dir ./test-model

hfjs --help
hfjs  upload --help

hfjs help jobs
hfjs download --help
```

## OAuth Login

It's possible to login using OAuth (["Sign in with HF"](https://huggingface.co/docs/hub/oauth)).

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.

```ts
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
console.log(oauthResult);
```

Checkout the demo: https://huggingface.co/spaces/huggingfacejs/client-side-oauth

## Hugging face cache

The `@huggingface/hub` package provide basic capabilities to scan the cache directory. Learn more about [Manage huggingface_hub cache-system](https://huggingface.co/docs/huggingface_hub/en/guides/manage-cache).

### `scanCacheDir`

You can get the list of cached repositories using the `scanCacheDir` function.

```ts
import { scanCacheDir } from "@huggingface/hub";

const result = await scanCacheDir();

console.log(result);
```
Note: this does not work in the browser

### `downloadFileToCacheDir`

You can cache a file of a repository using the `downloadFileToCacheDir` function.

```ts
import { downloadFileToCacheDir } from "@huggingface/hub";

const file = await downloadFileToCacheDir({
  repo: 'foo/bar',
  path: 'README.md'
});

console.log(file);
```
Note: this does not work in the browser

### `snapshotDownload`

You can download an entire repository at a given revision in the cache directory using the `snapshotDownload` function.

```ts
import { snapshotDownload } from "@huggingface/hub";

const directory = await snapshotDownload({
  repo: 'foo/bar',
});

console.log(directory);
```
The code use internally the `downloadFileToCacheDir` function.

Note: this does not work in the browser

## 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.

To edit an existing file, prefer an `edit` commit operation with the blob returned by `downloadFile` as `originalContent`: only the edited regions are downloaded, re-chunked and hashed. For repeated appends to the same file, pass a shared `rangeEditCache: new Map()` to the `commit` calls to also skip the storage-metadata round-trips.

## Dependencies

- `@huggingface/tasks` : Typings only

---
_Source: https://npm.io/package/@huggingface/hub · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._