Huggingface.js documentation

@huggingface/hub

Huggingface.js

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

@huggingface/hub

Classes

Interfaces

Type Aliases

AccessToken

Ƭ AccessToken: string

Actually hf_${string}, but for convenience, using the string type

Defined in

hub/src/types/public.ts:15

AccessTokenRole

Ƭ AccessTokenRole: "admin" | "write" | "contributor" | "read"

Defined in

hub/src/types/public.ts:70

AuthType

Ƭ AuthType: "access_token" | "app_token" | "app_token_as_user"

CommitParams

Ƭ CommitParams: { abortSignal?: AbortSignal ; branch?: string ; description?: string ; fetch?: typeof fetch ; hubUrl?: string ; isPullRequest?: boolean ; operations: CommitOperation[] ; parentCommit?: string ; repo: RepoDesignation ; title: string ; useWebWorkers?: boolean | { minSize?: number ; poolSize?: number } } & Partial\<CredentialsParams>

Defined in

hub/src/lib/commit.ts:57

CommitProgressEvent

Ƭ CommitProgressEvent: { event: "phase" ; phase: "preuploading" | "uploadingLargeFiles" | "committing" } | { event: "fileProgress" ; path: string ; progress: number ; state: "hashing" | "uploading" }

Defined in

hub/src/lib/commit.ts:106

ContentSource

Ƭ ContentSource: Blob | URL

Defined in

hub/src/lib/commit.ts:35

Dtype

Ƭ Dtype: "F64" | "F32" | "F16" | "BF16" | "I64" | "I32" | "I16" | "I8" | "U8" | "BOOL"

Defined in

hub/src/lib/parse-safetensors-metadata.ts:45

PipelineType

Ƭ PipelineType: keyof typeof PIPELINE_DATA

Defined in

tasks/dist/commonjs/pipelines.d.ts:426

RepoDesignation

Ƭ RepoDesignation: RepoId | RepoFullName

Defined in

hub/src/types/public.ts:12

RepoFullName

Ƭ RepoFullName: string | `spaces/${string}` | `datasets/${string}`

Defined in

hub/src/types/public.ts:10

RepoType

Ƭ RepoType: "space" | "dataset" | "model"

Defined in

hub/src/types/public.ts:3

SafetensorsFileHeader

Ƭ SafetensorsFileHeader: Record\<TensorName, TensorInfo> & { __metadata__: Record\<string, string> }

Defined in

hub/src/lib/parse-safetensors-metadata.ts:53

SafetensorsParseFromRepo

Ƭ SafetensorsParseFromRepo: { header: SafetensorsFileHeader ; parameterCount?: Partial\<Record\<Dtype, number>> ; sharded: false } | { headers: SafetensorsShardedHeaders ; index: SafetensorsIndexJson ; parameterCount?: Partial\<Record\<Dtype, number>> ; sharded: true }

Defined in

hub/src/lib/parse-safetensors-metadata.ts:67

SafetensorsShardedHeaders

Ƭ SafetensorsShardedHeaders: Record\<FileName, SafetensorsFileHeader>

Defined in

hub/src/lib/parse-safetensors-metadata.ts:65

SpaceHardwareFlavor

Defined in

hub/src/types/public.ts:40

SpaceSdk

Ƭ SpaceSdk: "streamlit" | "gradio" | "docker" | "static"

Defined in

hub/src/types/public.ts:56

SpaceStage

Defined in

hub/src/types/public.ts:58

TensorName

Ƭ TensorName: string

Defined in

hub/src/lib/parse-safetensors-metadata.ts:44

WhoAmI

Ƭ WhoAmI: WhoAmIApp | WhoAmIOrg | WhoAmIUser

Defined in

hub/src/lib/who-am-i.ts:50

Variables

DATASET _ EXPANDABLE _ KEYS

• Const DATASET_EXPANDABLE_KEYS: readonly ["author", "cardData", "citation", "createdAt", "disabled", "description", "downloads", "downloadsAllTime", "gated", "gitalyUid", "lastModified", "likes", "paperswithcode_id", "private", "sha", "tags"]

Defined in

hub/src/lib/list-datasets.ts:17

DATASET _ EXPAND _ KEYS

• Const DATASET_EXPAND_KEYS: readonly ["private", "downloads", "gated", "likes", "lastModified"]

Defined in

hub/src/lib/list-datasets.ts:9

DEFAULT _ REVISION

• Const DEFAULT_REVISION: "main"

Defined in

hub/src/lib/snapshot-download.ts:12

MODEL _ EXPANDABLE _ KEYS

• Const MODEL_EXPANDABLE_KEYS: readonly ["author", "cardData", "config", "createdAt", "disabled", "downloads", "downloadsAllTime", "gated", "gitalyUid", "lastModified", "library_name", "likes", "model-index", "pipeline_tag", "private", "safetensors", "sha", "spaces", "tags", "transformersInfo"]

Defined in

hub/src/lib/list-models.ts:18

MODEL _ EXPAND _ KEYS

• Const MODEL_EXPAND_KEYS: readonly ["pipeline_tag", "private", "gated", "downloads", "likes", "lastModified"]

Defined in

hub/src/lib/list-models.ts:9

REGEX _ COMMIT _ HASH

• Const REGEX_COMMIT_HASH: RegExp

Defined in

hub/src/lib/download-file-to-cache-dir.ts:10

REPO _ ID _ SEPARATOR

• Const REPO_ID_SEPARATOR: string = "--"

Defined in

hub/src/lib/cache-management.ts:25

RE _ SAFETENSORS _ FILE

• Const RE_SAFETENSORS_FILE: RegExp

Defined in

hub/src/lib/parse-safetensors-metadata.ts:14

RE _ SAFETENSORS _ INDEX _ FILE

• Const RE_SAFETENSORS_INDEX_FILE: RegExp

Defined in

hub/src/lib/parse-safetensors-metadata.ts:15

RE _ SAFETENSORS _ SHARD _ FILE

• Const RE_SAFETENSORS_SHARD_FILE: RegExp

Defined in

hub/src/lib/parse-safetensors-metadata.ts:16

SAFETENSORS _ FILE

• Const SAFETENSORS_FILE: "model.safetensors"

Defined in

hub/src/lib/parse-safetensors-metadata.ts:10

SAFETENSORS _ INDEX _ FILE

• Const SAFETENSORS_INDEX_FILE: "model.safetensors.index.json"

Defined in

hub/src/lib/parse-safetensors-metadata.ts:11

SPACE _ EXPANDABLE _ KEYS

• Const SPACE_EXPANDABLE_KEYS: readonly ["author", "cardData", "datasets", "disabled", "gitalyUid", "lastModified", "createdAt", "likes", "private", "runtime", "sdk", "sha", "subdomain", "tags", "models"]

Defined in

hub/src/lib/list-spaces.ts:15

SPACE _ EXPAND _ KEYS

• Const SPACE_EXPAND_KEYS: readonly ["sdk", "likes", "private", "lastModified"]

Defined in

hub/src/lib/list-spaces.ts:9

Functions

_ _ internal _ sha256

▸ __internal_sha256(buffer, opts?): AsyncGenerator\<number, string>

Parameters

Name	Type
`buffer`	`Blob`
`opts?`	`Object`
`opts.abortSignal?`	`AbortSignal`
`opts.useWebWorker?`	`boolean` \| { `minSize?`: `number` ; `poolSize?`: `number` }

Returns

AsyncGenerator\<number, string>

hex-encoded sha

Yields

progress (0-1)

Defined in

hub/src/utils/sha256.ts:72

checkRepoAccess

▸ checkRepoAccess(params): Promise\<void>

Check if we have read access to a repository.

Throw a HubApiError error if we don’t have access. HubApiError.statusCode will be 401, 403 or 404.

Parameters

Name	Type
`params`	{ `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `repo`: `RepoDesignation` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<void>

Defined in

hub/src/lib/check-repo-access.ts:13

commit

▸ commit(params): Promise\<CommitOutput>

Parameters

Name	Type
`params`	`CommitParams`

Returns

Promise\<CommitOutput>

Defined in

hub/src/lib/commit.ts:553

commitIter

▸ commitIter(params): AsyncGenerator\<CommitProgressEvent, CommitOutput>

Internal function for now, used by commit.

Can be exposed later to offer fine-tuned progress info

Parameters

Name	Type
`params`	`CommitParams`

Returns

AsyncGenerator\<CommitProgressEvent, CommitOutput>

Defined in

hub/src/lib/commit.ts:123

countCommits

▸ countCommits(params): Promise\<number>

Parameters

Name	Type
`params`	{ `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `repo`: `RepoDesignation` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<number>

Defined in

hub/src/lib/count-commits.ts:7

createRepo

▸ createRepo(params): Promise\<{ repoUrl: string }>

Parameters

Name Type

params { fetch?: (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> ; files?: { content: ArrayBuffer | Blob ; path: string }[] ; hubUrl?: string ; license?: string ; private?: boolean ; repo: RepoDesignation ; sdk?: SpaceSdk | undefined } & CredentialsParams

Name	Type
`params`	{ `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `files?`: { `content`: `ArrayBuffer` \| `Blob` ; `path`: `string` }[] ; `hubUrl?`: `string` ; `license?`: `string` ; `private?`: `boolean` ; `repo`: `RepoDesignation` ; `sdk?`: SpaceSdk \| undefined } & `CredentialsParams`

Returns

Promise\<{ repoUrl: string }>

Defined in

hub/src/lib/create-repo.ts:9

datasetInfo

▸ datasetInfo\<T>(params): Promise\<DatasetEntry & Pick\<ApiDatasetInfo, T>>

Type parameters

Name	Type
`T`	extends `"author"` \| `"cardData"` \| `"disabled"` \| `"gitalyUid"` \| `"createdAt"` \| `"tags"` \| `"paperswithcode_id"` \| `"sha"` \| `"citation"` \| `"description"` \| `"downloadsAllTime"` = `never`

Parameters

Name	Type
`params`	{ `additionalFields?`: `T`[] ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `name`: `string` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<DatasetEntry & Pick\<ApiDatasetInfo, T>>

Defined in

hub/src/lib/dataset-info.ts:9

deleteFile

▸ deleteFile(params): Promise\<CommitOutput>

Parameters

Name Type

params { branch?: string ; commitDescription?: string ; commitTitle?: string ; fetch?: (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> ; hubUrl?: string ; isPullRequest?: boolean ; parentCommit?: string ; path: string ; repo: RepoDesignation } & CredentialsParams

Name	Type
`params`	{ `branch?`: `string` ; `commitDescription?`: `string` ; `commitTitle?`: `string` ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `isPullRequest?`: `boolean` ; `parentCommit?`: `string` ; `path`: `string` ; `repo`: `RepoDesignation` } & `CredentialsParams`

Returns

Promise\<CommitOutput>

Defined in

hub/src/lib/delete-file.ts:5

deleteFiles

▸ deleteFiles(params): Promise\<CommitOutput>

Parameters

Name Type

params { branch?: string ; commitDescription?: string ; commitTitle?: string ; fetch?: (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> ; hubUrl?: string ; isPullRequest?: boolean ; parentCommit?: string ; paths: string[] ; repo: RepoDesignation } & CredentialsParams

Name	Type
`params`	{ `branch?`: `string` ; `commitDescription?`: `string` ; `commitTitle?`: `string` ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `isPullRequest?`: `boolean` ; `parentCommit?`: `string` ; `paths`: `string`[] ; `repo`: `RepoDesignation` } & `CredentialsParams`

Returns

Promise\<CommitOutput>

Defined in

hub/src/lib/delete-files.ts:5

deleteRepo

▸ deleteRepo(params): Promise\<void>

Parameters

Name	Type
`params`	{ `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `repo`: `RepoDesignation` } & `CredentialsParams`

Returns

Promise\<void>

Defined in

hub/src/lib/delete-repo.ts:7

downloadFile

▸ downloadFile(params): Promise\<Response | null>

Parameters

Name	Type
`params`	{ `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `path`: `string` ; `range?`: [`number`, `number`] ; `raw?`: `boolean` ; `repo`: `RepoDesignation` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<Response | null>

null when the file doesn’t exist

Defined in

hub/src/lib/download-file.ts:10

downloadFileToCacheDir

▸ downloadFileToCacheDir(params): Promise\<string>

Download a given file if it’s not already present in the local cache.

Parameters

Name	Type
`params`	{ `cacheDir?`: `string` ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `path`: `string` ; `raw?`: `boolean` ; `repo`: `RepoDesignation` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<string>

the symlink to the blob object

Defined in

hub/src/lib/download-file-to-cache-dir.ts:40

fileDownloadInfo

▸ fileDownloadInfo(params): Promise\<FileDownloadInfoOutput | null>

Parameters

Name	Type
`params`	{ `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `noContentDisposition?`: `boolean` ; `path`: `string` ; `raw?`: `boolean` ; `repo`: `RepoDesignation` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<FileDownloadInfoOutput | null>

null when the file doesn’t exist

Defined in

hub/src/lib/file-download-info.ts:18

fileExists

▸ fileExists(params): Promise\<boolean>

Parameters

Name	Type
`params`	{ `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `path`: `string` ; `repo`: `RepoDesignation` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<boolean>

Defined in

hub/src/lib/file-exists.ts:7

getBlobStat

▸ getBlobStat(blobPath, blobStats): Promise\<Stats>

Parameters

Name	Type
`blobPath`	`string`
`blobStats`	`Map`\<`string`, `Stats`>

Returns

Promise\<Stats>

Defined in

hub/src/lib/cache-management.ts:244

getHFHubCachePath

▸ getHFHubCachePath(): string

Returns

string

Defined in

hub/src/lib/cache-management.ts:19

getRepoFolderName

▸ getRepoFolderName(«destructured»): string

Parameters

Name	Type
`«destructured»`	`RepoId`

Returns

string

Defined in

hub/src/lib/cache-management.ts:27

listCommits

▸ listCommits(params): AsyncGenerator\<CommitData>

Parameters

Name	Type
`params`	{ `batchSize?`: `number` ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `repo`: `RepoDesignation` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

AsyncGenerator\<CommitData>

Defined in

hub/src/lib/list-commits.ts:17

listDatasets

▸ listDatasets\<T>(params?): AsyncGenerator\<DatasetEntry & Pick\<ApiDatasetInfo, T>>

Type parameters

Name	Type
`T`	extends `"author"` \| `"cardData"` \| `"disabled"` \| `"gitalyUid"` \| `"createdAt"` \| `"tags"` \| `"paperswithcode_id"` \| `"sha"` \| `"citation"` \| `"description"` \| `"downloadsAllTime"` = `never`

Parameters

Name	Type
`params?`	{ search?: { query?: string \| undefined; owner?: string \| undefined; tags?: string[] \| undefined; } \| undefined; hubUrl?: string \| undefined; additionalFields?: T[] \| undefined; limit?: number \| undefined; fetch?: { …; } \| undefined; } & Partial\<…>

Returns

AsyncGenerator\<DatasetEntry & Pick\<ApiDatasetInfo, T>>

Defined in

hub/src/lib/list-datasets.ts:47

listFiles

▸ listFiles(params): AsyncGenerator\<ListFileEntry>

List files in a folder. To list ALL files in the directory, call it with params.recursive set to true.

Parameters

Name	Type
`params`	{ `expand?`: `boolean` ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `path?`: `string` ; `recursive?`: `boolean` ; `repo`: `RepoDesignation` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

AsyncGenerator\<ListFileEntry>

Defined in

hub/src/lib/list-files.ts:38

listModels

▸ listModels\<T>(params?): AsyncGenerator\<ModelEntry & Pick\<ApiModelInfo, T>>

Type parameters

Name	Type
`T`	extends `"spaces"` \| `"author"` \| `"cardData"` \| `"disabled"` \| `"gitalyUid"` \| `"createdAt"` \| `"tags"` \| `"sha"` \| `"downloadsAllTime"` \| `"config"` \| `"library_name"` \| `"model-index"` \| `"safetensors"` \| `"transformersInfo"` = `never`

Parameters

Name	Type
`params?`	{ search?: { query?: string \| undefined; owner?: string \| undefined; task?: “other” \| “text-classification” \| “token-classification” \| “table-question-answering” \| “question-answering” \| … 48 more … \| undefined; tags?: string[] \| undefined; } \| undefined; hubUrl?: string \| undefined; additionalFields?: T[] \| und…

Returns

AsyncGenerator\<ModelEntry & Pick\<ApiModelInfo, T>>

Defined in

hub/src/lib/list-models.ts:53

listSpaces

▸ listSpaces\<T>(params?): AsyncGenerator\<SpaceEntry & Pick\<ApiSpaceInfo, T>>

Type parameters

Name	Type
`T`	extends `"models"` \| `"datasets"` \| `"author"` \| `"cardData"` \| `"disabled"` \| `"gitalyUid"` \| `"createdAt"` \| `"tags"` \| `"sha"` \| `"subdomain"` \| `"runtime"` = `never`

Parameters

Name	Type
`params?`	{ search?: { query?: string \| undefined; owner?: string \| undefined; tags?: string[] \| undefined; } \| undefined; hubUrl?: string \| undefined; fetch?: { (input: URL \| RequestInfo, init?: RequestInit \| undefined): Promise\<…>; (input: string \| … 1 more … \| Request, init?: RequestInit \| undefined): Promise\<…>; }…

Returns

AsyncGenerator\<SpaceEntry & Pick\<ApiSpaceInfo, T>>

Defined in

hub/src/lib/list-spaces.ts:44

modelInfo

▸ modelInfo\<T>(params): Promise\<ModelEntry & Pick\<ApiModelInfo, T>>

Type parameters

Name	Type
`T`	extends `"spaces"` \| `"author"` \| `"cardData"` \| `"disabled"` \| `"gitalyUid"` \| `"createdAt"` \| `"tags"` \| `"sha"` \| `"downloadsAllTime"` \| `"config"` \| `"library_name"` \| `"model-index"` \| `"safetensors"` \| `"transformersInfo"` = `never`

Parameters

Name	Type
`params`	{ `additionalFields?`: `T`[] ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `name`: `string` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<ModelEntry & Pick\<ApiModelInfo, T>>

Defined in

hub/src/lib/model-info.ts:9

oauthHandleRedirect

▸ oauthHandleRedirect(opts?): Promise\<OAuthResult>

To call after the OAuth provider redirects back to the app.

There is also a helper function oauthHandleRedirectIfPresent, which will call oauthHandleRedirect if the URL contains an oauth code in the query parameters and return false otherwise.

Parameters

Name	Type	Description
`opts?`	`Object`	-
`opts.codeVerifier?`	`string`	codeVerifier generated by oauthLoginUrl `Default` `ts localStorage.getItem("huggingface.co:oauth:code_verifier")`
`opts.hubUrl?`	`string`	The URL of the hub. Defaults to HUB_URL.
`opts.nonce?`	`string`	nonce generated by oauthLoginUrl `Default` `ts localStorage.getItem("huggingface.co:oauth:nonce")`
`opts.redirectedUrl?`	`string`	The URL to analyze. `Default` `ts window.location.href`

Returns

Promise\<OAuthResult>

Defined in

hub/src/lib/oauth-handle-redirect.ts:114

oauthHandleRedirectIfPresent

▸ oauthHandleRedirectIfPresent(opts?): Promise\<OAuthResult | false>

To call after the OAuth provider redirects back to the app.

It returns false if the URL does not contain an oauth code in the query parameters, otherwise it calls oauthHandleRedirect.

Depending on your app, you may want to call oauthHandleRedirect directly instead.

Parameters

Name	Type	Description
`opts?`	`Object`	-
`opts.codeVerifier?`	`string`	codeVerifier generated by oauthLoginUrl `Default` `ts localStorage.getItem("huggingface.co:oauth:code_verifier")`
`opts.hubUrl?`	`string`	The URL of the hub. Defaults to HUB_URL.
`opts.nonce?`	`string`	nonce generated by oauthLoginUrl `Default` `ts localStorage.getItem("huggingface.co:oauth:nonce")`
`opts.redirectedUrl?`	`string`	The URL to analyze. `Default` `ts window.location.href`

Returns

Promise\<OAuthResult | false>

Defined in

hub/src/lib/oauth-handle-redirect.ts:284

oauthLoginUrl

▸ oauthLoginUrl(opts?): Promise\<string>

Use “Sign in with Hub” to authenticate a user, and get oauth user info / access token.

Returns an url to redirect to. After the user is redirected back to your app, call oauthHandleRedirect to get the oauth user info / access token.

When called from inside a static Space with OAuth enabled, it will load the config from the space, otherwise you need to at least specify the client ID of your OAuth App.

Parameters

Name	Type	Description
`opts?`	`Object`	-
`opts.clientId?`	`string`	OAuth client ID. For static Spaces, you can omit this and it will be loaded from the Space config, as long as `hf_oauth: true` is present in the README.md’s metadata. For other Spaces, it is available to the backend in the OAUTH_CLIENT_ID environment variable, as long as `hf_oauth: true` is present in the README.md’s metadata. You can also create a Developer Application at https://huggingface.co/settings/connected-applications and use its client ID.
`opts.hubUrl?`	`string`	-
`opts.localStorage?`	`Object`	If provided, will be filled with the code verifier and nonce used for the OAuth flow, instead of using localStorage. When calling `oauthHandleRedirectIfPresent` or `oauthHandleRedirect` you will need to provide the same values.
`opts.localStorage.codeVerifier?`	`string`	-
`opts.localStorage.nonce?`	`string`	-
`opts.redirectUrl?`	`string`	Redirect URI, defaults to the current URL. For Spaces, any URL within the Space is allowed. For Developer Applications, you can add any URL you want to the list of allowed redirect URIs at https://huggingface.co/settings/connected-applications.
`opts.scopes?`	`string`	OAuth scope, a list of space-separated scopes. For static Spaces, you can omit this and it will be loaded from the Space config, as long as `hf_oauth: true` is present in the README.md’s metadata. For other Spaces, it is available to the backend in the OAUTH_SCOPES environment variable, as long as `hf_oauth: true` is present in the README.md’s metadata. Defaults to “openid profile”. You can also create a Developer Application at https://huggingface.co/settings/connected-applications and use its scopes. See https://huggingface.co/docs/hub/oauth for a list of available scopes.
`opts.state?`	`string`	State to pass to the OAuth provider, which will be returned in the call to `oauthLogin` after the redirect.

Returns

Promise\<string>

Example

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);

(Theoretically, this function could be used to authenticate a user for any OAuth provider supporting PKCE and OpenID Connect by changing hubUrl, but it is currently only tested with the Hugging Face Hub.)

Defined in

hub/src/lib/oauth-login-url.ts:31

parseRepoType

▸ parseRepoType(type): RepoType

Parameters

Name	Type
`type`	`string`

Returns

RepoType

Defined in

hub/src/lib/cache-management.ts:254

parseSafetensorsMetadata

▸ parseSafetensorsMetadata(params): Promise\<SetRequired\<SafetensorsParseFromRepo, "parameterCount">>

Analyze model.safetensors.index.json or model.safetensors from a model hosted on Hugging Face using smart range requests to extract its metadata.

Parameters

Name	Type
`params`	{ `computeParametersCount`: `true` ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `path?`: `string` ; `repo`: `RepoDesignation` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<SetRequired\<SafetensorsParseFromRepo, "parameterCount">>

Defined in

hub/src/lib/parse-safetensors-metadata.ts:177

▸ parseSafetensorsMetadata(params): Promise\<SafetensorsParseFromRepo>

Parameters

Name	Type
`params`	{ `computeParametersCount?`: `boolean` ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `path?`: `string` ; `repo`: `RepoDesignation` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<SafetensorsParseFromRepo>

Defined in

hub/src/lib/parse-safetensors-metadata.ts:199

parseSafetensorsShardFilename

▸ parseSafetensorsShardFilename(filename): SafetensorsShardFileInfo | null

Parameters

Name	Type
`filename`	`string`

Returns

SafetensorsShardFileInfo | null

Defined in

hub/src/lib/parse-safetensors-metadata.ts:24

pathsInfo

▸ pathsInfo(params): Promise\<PathInfo & { lastCommit: CommitInfo ; securityFileStatus: SecurityFileStatus }[]>

Parameters

Name	Type
`params`	{ `expand`: `true` ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `paths`: `string`[] ; `repo`: `RepoDesignation` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<PathInfo & { lastCommit: CommitInfo ; securityFileStatus: SecurityFileStatus }[]>

Defined in

hub/src/lib/paths-info.ts:37

▸ pathsInfo(params): Promise\<PathInfo[]>

Parameters

Name	Type
`params`	{ `expand?`: `boolean` ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `paths`: `string`[] ; `repo`: `RepoDesignation` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<PathInfo[]>

Defined in

hub/src/lib/paths-info.ts:50

scanCacheDir

▸ scanCacheDir(cacheDir?): Promise\<HFCacheInfo>

Parameters

Name	Type	Default value
`cacheDir`	`undefined` \| `string`	`undefined`

Returns

Promise\<HFCacheInfo>

Defined in

hub/src/lib/cache-management.ts:72

scanCachedRepo

▸ scanCachedRepo(repoPath): Promise\<CachedRepoInfo>

Parameters

Name	Type
`repoPath`	`string`

Returns

Promise\<CachedRepoInfo>

Defined in

hub/src/lib/cache-management.ts:114

scanRefsDir

▸ scanRefsDir(refsPath, refsByHash): Promise\<void>

Parameters

Name	Type
`refsPath`	`string`
`refsByHash`	`Map`\<`string`, `string`[]>

Returns

Promise\<void>

Defined in

hub/src/lib/cache-management.ts:204

scanSnapshotDir

▸ scanSnapshotDir(revisionPath, cachedFiles, blobStats): Promise\<void>

Parameters

Name	Type
`revisionPath`	`string`
`cachedFiles`	`CachedFileInfo`[]
`blobStats`	`Map`\<`string`, `Stats`>

Returns

Promise\<void>

Defined in

hub/src/lib/cache-management.ts:219

snapshotDownload

▸ snapshotDownload(params): Promise\<string>

Downloads an entire repository at a given revision in the cache directory getHFHubCachePath. You can list all cached repositories using scanCachedRepo

Parameters

Name	Type
`params`	{ `cacheDir?`: `string` ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `repo`: `RepoDesignation` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<string>

Remarks

It uses internally downloadFileToCacheDir.

Defined in

hub/src/lib/snapshot-download.ts:19

spaceInfo

▸ spaceInfo\<T>(params): Promise\<SpaceEntry & Pick\<ApiSpaceInfo, T>>

Type parameters

Name	Type
`T`	extends `"models"` \| `"datasets"` \| `"author"` \| `"cardData"` \| `"disabled"` \| `"gitalyUid"` \| `"createdAt"` \| `"tags"` \| `"sha"` \| `"subdomain"` \| `"runtime"` = `never`

Parameters

Name	Type
`params`	{ `additionalFields?`: `T`[] ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` ; `name`: `string` ; `revision?`: `string` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<SpaceEntry & Pick\<ApiSpaceInfo, T>>

Defined in

hub/src/lib/space-info.ts:10

uploadFile

▸ uploadFile(params): Promise\<CommitOutput>

Parameters

Name Type

params { abortSignal?: AbortSignal ; branch?: string ; commitDescription?: string ; commitTitle?: string ; fetch?: (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> ; file: URL | File | { content: ContentSource ; path: string } ; hubUrl?: string ; isPullRequest?: boolean ; parentCommit?: string ; repo: RepoDesignation ; useWebWorkers?: boolean | { minSize?: number ; poolSize?: number } } & Partial\<CredentialsParams>

Name	Type
`params`	{ `abortSignal?`: `AbortSignal` ; `branch?`: `string` ; `commitDescription?`: `string` ; `commitTitle?`: `string` ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `file`: `URL` \| `File` \| { `content`: `ContentSource` ; `path`: `string` } ; `hubUrl?`: `string` ; `isPullRequest?`: `boolean` ; `parentCommit?`: `string` ; `repo`: `RepoDesignation` ; `useWebWorkers?`: `boolean` \| { `minSize?`: `number` ; `poolSize?`: `number` } } & `Partial`\<`CredentialsParams`>

Returns

Promise\<CommitOutput>

Defined in

hub/src/lib/upload-file.ts:5

uploadFiles

▸ uploadFiles(params): Promise\<CommitOutput>

Parameters

Name Type

params { abortSignal?: AbortSignal ; branch?: string ; commitDescription?: string ; commitTitle?: string ; fetch?: (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> ; files: (URL | File | { content: ContentSource ; path: string })[] ; hubUrl?: string ; isPullRequest?: boolean ; parentCommit?: string ; repo: RepoDesignation ; useWebWorkers?: boolean | { minSize?: number ; poolSize?: number } } & Partial\<CredentialsParams>

Name	Type
`params`	{ `abortSignal?`: `AbortSignal` ; `branch?`: `string` ; `commitDescription?`: `string` ; `commitTitle?`: `string` ; `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `files`: (`URL` \| `File` \| { `content`: `ContentSource` ; `path`: `string` })[] ; `hubUrl?`: `string` ; `isPullRequest?`: `boolean` ; `parentCommit?`: `string` ; `repo`: `RepoDesignation` ; `useWebWorkers?`: `boolean` \| { `minSize?`: `number` ; `poolSize?`: `number` } } & `Partial`\<`CredentialsParams`>

Returns

Promise\<CommitOutput>

Defined in

hub/src/lib/upload-files.ts:5

uploadFilesWithProgress

▸ uploadFilesWithProgress(params): AsyncGenerator\<CommitProgressEvent, CommitOutput>

Uploads with progress

Needs XMLHttpRequest to be available for progress events for uploads Set useWebWorkers to true in order to have progress events for hashing

Parameters

Name Type

params { abortSignal?: AbortSignal ; branch?: string ; commitDescription?: string ; commitTitle?: string ; files: (URL | File | { content: ContentSource ; path: string })[] ; hubUrl?: string ; isPullRequest?: boolean ; parentCommit?: string ; repo: RepoDesignation ; useWebWorkers?: boolean | { minSize?: number ; poolSize?: number } } & Partial\<CredentialsParams>

Name	Type
`params`	{ `abortSignal?`: `AbortSignal` ; `branch?`: `string` ; `commitDescription?`: `string` ; `commitTitle?`: `string` ; `files`: (`URL` \| `File` \| { `content`: `ContentSource` ; `path`: `string` })[] ; `hubUrl?`: `string` ; `isPullRequest?`: `boolean` ; `parentCommit?`: `string` ; `repo`: `RepoDesignation` ; `useWebWorkers?`: `boolean` \| { `minSize?`: `number` ; `poolSize?`: `number` } } & `Partial`\<`CredentialsParams`>

Returns

AsyncGenerator\<CommitProgressEvent, CommitOutput>

Defined in

hub/src/lib/upload-files-with-progress.ts:20

whoAmI

▸ whoAmI(params): Promise\<WhoAmI & { auth: AuthInfo }>

Parameters

Name	Type
`params`	{ `fetch?`: (`input`: URL \| RequestInfo, `init?`: `RequestInit`) => `Promise`\<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`\<`Response`> ; `hubUrl?`: `string` } & `CredentialsParams`

Returns

Promise\<WhoAmI & { auth: AuthInfo }>

Defined in

hub/src/lib/who-am-i.ts:61

< > Update on GitHub

←Interact with the Hub HubApiError→