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

packages/hub/src/types/public.ts:15

AccessTokenRole

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

Defined in

packages/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 __type ; hubUrl?: string ; isPullRequest?: boolean ; maxFolderDepth?: number ; operations: CommitOperation[] ; parentCommit?: string ; repo: RepoDesignation ; title: string ; useWebWorkers?: boolean | { minSize?: number ; poolSize?: number } } & Partial\<CredentialsParams>

Defined in

packages/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

packages/hub/src/lib/commit.ts:112

ContentSource

Ƭ ContentSource: Blob | URL

Defined in

packages/hub/src/lib/commit.ts:35

Dtype

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

Defined in

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

PipelineType

Ƭ PipelineType: keyof typeof PIPELINE_DATA

Defined in

packages/tasks/dist/commonjs/pipelines.d.ts:437

RepoDesignation

Ƭ RepoDesignation: RepoId | RepoFullName

Defined in

packages/hub/src/types/public.ts:12

RepoFullName

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

Defined in

packages/hub/src/types/public.ts:10

RepoType

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

Defined in

packages/hub/src/types/public.ts:3

SafetensorsFileHeader

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

Defined in

packages/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

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

SafetensorsShardedHeaders

Ƭ SafetensorsShardedHeaders: Record\<FileName, SafetensorsFileHeader>

Defined in

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

SpaceHardwareFlavor

Defined in

packages/hub/src/types/public.ts:40

SpaceSdk

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

Defined in

packages/hub/src/types/public.ts:56

SpaceStage

Defined in

packages/hub/src/types/public.ts:58

TensorName

Ƭ TensorName: string

Defined in

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

WhoAmI

Ƭ WhoAmI: WhoAmIApp | WhoAmIOrg | WhoAmIUser

Defined in

packages/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

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

DATASET _ EXPAND _ KEYS

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

Defined in

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

DEFAULT _ REVISION

• Const DEFAULT_REVISION: "main"

Defined in

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

MODEL _ EXPANDABLE _ KEYS

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

Defined in

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

MODEL _ EXPAND _ KEYS

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

Defined in

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

REGEX _ COMMIT _ HASH

• Const REGEX_COMMIT_HASH: RegExp

Defined in

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

REPO _ ID _ SEPARATOR

• Const REPO_ID_SEPARATOR: string = "--"

Defined in

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

RE _ SAFETENSORS _ FILE

• Const RE_SAFETENSORS_FILE: RegExp

Defined in

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

RE _ SAFETENSORS _ INDEX _ FILE

• Const RE_SAFETENSORS_INDEX_FILE: RegExp

Defined in

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

RE _ SAFETENSORS _ SHARD _ FILE

• Const RE_SAFETENSORS_SHARD_FILE: RegExp

Defined in

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

SAFETENSORS _ FILE

• Const SAFETENSORS_FILE: "model.safetensors"

Defined in

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

SAFETENSORS _ INDEX _ FILE

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

Defined in

packages/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

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

SPACE _ EXPAND _ KEYS

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

Defined in

packages/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

packages/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

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

commit

▸ commit(params): Promise\<CommitOutput>

Parameters

Name	Type
`params`	`CommitParams`

Returns

Promise\<CommitOutput>

Defined in

packages/hub/src/lib/commit.ts:565

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

packages/hub/src/lib/commit.ts:129

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

packages/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

packages/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

packages/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

packages/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

packages/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

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

downloadFile

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

Parameters

Name	Type
`params`	{ `downloadInfo?`: `FileDownloadInfoOutput` ; `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` ; `xet?`: `boolean` } & `Partial`\<`CredentialsParams`>

Returns

Promise\<Blob | null>

null when the file doesn’t exist

Defined in

packages/hub/src/lib/download-file.ts:11

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

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

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

packages/hub/src/lib/file-download-info.ts:27

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

packages/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

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

getHFHubCachePath

▸ getHFHubCachePath(): string

Returns

string

Defined in

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

getRepoFolderName

▸ getRepoFolderName(«destructured»): string

Parameters

Name	Type
`«destructured»`	`RepoId`

Returns

string

Defined in

packages/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

packages/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

packages/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

packages/hub/src/lib/list-files.ts:42

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"` \| `"inferenceProviderMapping"` \| `"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” \| … 50 more … \| undefined; tags?: string[] \| undefined; inferenceProviders?: string[] \| undefined; } \| undefined; hubUrl?: strin…

Returns

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

Defined in

packages/hub/src/lib/list-models.ts:54

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

packages/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"` \| `"inferenceProviderMapping"` \| `"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

packages/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

packages/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

packages/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

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

parseRepoType

▸ parseRepoType(type): RepoType

Parameters

Name	Type
`type`	`string`

Returns

RepoType

Defined in

packages/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

packages/hub/src/lib/parse-safetensors-metadata.ts:166

▸ 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

packages/hub/src/lib/parse-safetensors-metadata.ts:188

parseSafetensorsShardFilename

▸ parseSafetensorsShardFilename(filename): SafetensorsShardFileInfo | null

Parameters

Name	Type
`filename`	`string`

Returns

SafetensorsShardFileInfo | null

Defined in

packages/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

packages/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

packages/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

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

scanCachedRepo

▸ scanCachedRepo(repoPath): Promise\<CachedRepoInfo>

Parameters

Name	Type
`repoPath`	`string`

Returns

Promise\<CachedRepoInfo>

Defined in

packages/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

packages/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

packages/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

packages/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

packages/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

packages/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 ; maxFolderDepth?: number ; 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` ; `maxFolderDepth?`: `number` ; `parentCommit?`: `string` ; `repo`: `RepoDesignation` ; `useWebWorkers?`: `boolean` \| { `minSize?`: `number` ; `poolSize?`: `number` } } & `Partial`\<`CredentialsParams`>

Returns

Promise\<CommitOutput>

Defined in

packages/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 ; maxFolderDepth?: number ; 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` ; `maxFolderDepth?`: `number` ; `parentCommit?`: `string` ; `repo`: `RepoDesignation` ; `useWebWorkers?`: `boolean` \| { `minSize?`: `number` ; `poolSize?`: `number` } } & `Partial`\<`CredentialsParams`>

Returns

AsyncGenerator\<CommitProgressEvent, CommitOutput>

Defined in

packages/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

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

< > Update on GitHub

←Interact with the Hub HubApiError→