@huggingface/hub
Classes
Interfaces
- AuthInfo
- CommitDeletedEntry
- CommitFile
- CommitOutput
- CommitParams
- Credentials
- DatasetEntry
- FileDownloadInfoOutput
- ListFileEntry
- ModelEntry
- OAuthResult
- RepoId
- SafetensorsIndexJson
- SafetensorsShardFileInfo
- SpaceEntry
- SpaceResourceConfig
- SpaceResourceRequirement
- SpaceRuntime
- TensorInfo
- WhoAmIApp
- WhoAmIOrg
- WhoAmIUser
Type Aliases
AccessToken
Ƭ AccessToken: string
Actually hf_${string}, but for convenience, using the string type
Defined in
AccessTokenRole
Ƭ AccessTokenRole: "admin" | "write" | "contributor" | "read"
Defined in
AuthType
Ƭ AuthType: "access_token" | "app_token" | "app_token_as_user"
Defined in
CommitOperation
Ƭ CommitOperation: CommitDeletedEntry | CommitFile
Defined in
CommitProgressEvent
Ƭ CommitProgressEvent: { event: "phase" ; phase: "preuploading" | "uploadingLargeFiles" | "committing" } | { event: "fileProgress" ; path: string ; progress: number ; state: "hashing" | "uploading" }
Defined in
ContentSource
Ƭ ContentSource: Blob | URL
Defined in
Dtype
Ƭ Dtype: "F64" | "F32" | "F16" | "BF16" | "I64" | "I32" | "I16" | "I8" | "U8" | "BOOL"
Defined in
hub/src/lib/parse-safetensors-metadata.ts:46
PipelineType
Ƭ PipelineType: keyof typeof PIPELINE_DATA
Defined in
tasks/dist/index.d.ts:399
RepoDesignation
Ƭ RepoDesignation: RepoId | RepoFullName
Defined in
RepoFullName
Ƭ RepoFullName: string | `spaces/${string}` | `datasets/${string}`
Defined in
RepoType
Ƭ RepoType: "space" | "dataset" | "model"
Defined in
SafetensorsFileHeader
Ƭ SafetensorsFileHeader: Record\<TensorName, TensorInfo> & { __metadata__: Record\<string, string> }
Defined in
hub/src/lib/parse-safetensors-metadata.ts:54
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:68
SafetensorsShardedHeaders
Ƭ SafetensorsShardedHeaders: Record\<FileName, SafetensorsFileHeader>
Defined in
hub/src/lib/parse-safetensors-metadata.ts:66
SpaceHardwareFlavor
Ƭ SpaceHardwareFlavor: "cpu-basic" | "cpu-upgrade" | "t4-small" | "t4-medium" | "a10g-small" | "a10g-large" | "a100-large"
Defined in
SpaceSdk
Ƭ SpaceSdk: "streamlit" | "gradio" | "docker" | "static"
Defined in
SpaceStage
Ƭ SpaceStage: "NO_APP_FILE" | "CONFIG_ERROR" | "BUILDING" | "BUILD_ERROR" | "RUNNING" | "RUNNING_BUILDING" | "RUNTIME_ERROR" | "DELETING" | "PAUSED" | "SLEEPING"
Defined in
TensorName
Ƭ TensorName: string
Defined in
hub/src/lib/parse-safetensors-metadata.ts:45
WhoAmI
Ƭ WhoAmI: WhoAmIApp | WhoAmIOrg | WhoAmIUser
Defined in
Variables
RE _ SAFETENSORS _ FILE
• Const RE_SAFETENSORS_FILE: RegExp
Defined in
hub/src/lib/parse-safetensors-metadata.ts:15
RE _ SAFETENSORS _ INDEX _ FILE
• Const RE_SAFETENSORS_INDEX_FILE: RegExp
Defined in
hub/src/lib/parse-safetensors-metadata.ts:16
RE _ SAFETENSORS _ SHARD _ FILE
• Const RE_SAFETENSORS_SHARD_FILE: RegExp
Defined in
hub/src/lib/parse-safetensors-metadata.ts:17
SAFETENSORS _ FILE
• Const SAFETENSORS_FILE: "model.safetensors"
Defined in
hub/src/lib/parse-safetensors-metadata.ts:11
SAFETENSORS _ INDEX _ FILE
• Const SAFETENSORS_INDEX_FILE: "model.safetensors.index.json"
Defined in
hub/src/lib/parse-safetensors-metadata.ts:12
Functions
commit
▸ commit(params): Promise\<CommitOutput>
Parameters
| Name | Type |
|---|---|
params | CommitParams |
Returns
Promise\<CommitOutput>
Defined in
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
createRepo
▸ createRepo(params): Promise\<{ repoUrl: string }>
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.credentials | Credentials | - |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> | Custom fetch function to use instead of the default one, for example to use a proxy or edit headers. |
params.files? | { content: ArrayBuffer | Blob ; path: string }[] | Only a few lightweight files are supported at repo creation |
params.hubUrl? | string | - |
params.license? | string | - |
params.private? | boolean | - |
params.repo | RepoDesignation | - |
params.sdk? | SpaceSdk | Required for when repo.type === “space” |
Returns
Promise\<{ repoUrl: string }>
Defined in
deleteFile
▸ deleteFile(params): Promise\<CommitOutput>
Parameters
| Name | Type |
|---|---|
params | Object |
params.branch? | string |
params.commitDescription? | string |
params.commitTitle? | string |
params.credentials | Credentials |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> |
params.hubUrl? | string |
params.isPullRequest? | boolean |
params.parentCommit? | string |
params.path | string |
params.repo | RepoDesignation |
Returns
Promise\<CommitOutput>
Defined in
deleteFiles
▸ deleteFiles(params): Promise\<CommitOutput>
Parameters
| Name | Type |
|---|---|
params | Object |
params.branch? | string |
params.commitDescription? | string |
params.commitTitle? | string |
params.credentials | Credentials |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> |
params.hubUrl? | string |
params.isPullRequest? | boolean |
params.parentCommit? | string |
params.paths | string[] |
params.repo | RepoDesignation |
Returns
Promise\<CommitOutput>
Defined in
deleteRepo
▸ deleteRepo(params): Promise\<void>
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.credentials | Credentials | - |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> | Custom fetch function to use instead of the default one, for example to use a proxy or edit headers. |
params.hubUrl? | string | - |
params.repo | RepoDesignation | - |
Returns
Promise\<void>
Defined in
downloadFile
▸ downloadFile(params): Promise\<Response | null>
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.credentials? | Credentials | - |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> | Custom fetch function to use instead of the default one, for example to use a proxy or edit headers. |
params.hubUrl? | string | - |
params.path | string | - |
params.range? | [number, number] | Fetch only a specific part of the file |
params.raw? | boolean | If true, will download the raw git file. For example, when calling on a file stored with Git LFS, the pointer file will be downloaded instead. |
params.repo | RepoDesignation | - |
params.revision? | string | - |
Returns
Promise\<Response | null>
null when the file doesn’t exist
Defined in
hub/src/lib/download-file.ts:10
fileDownloadInfo
▸ fileDownloadInfo(params): Promise\<FileDownloadInfoOutput | null>
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.credentials? | Credentials | - |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> | Custom fetch function to use instead of the default one, for example to use a proxy or edit headers. |
params.hubUrl? | string | - |
params.noContentDisposition? | boolean | To avoid the content-disposition header in the downloadLink for LFS files So that on browsers you can use the URL in an iframe for example |
params.path | string | - |
params.raw? | boolean | To get the raw pointer file behind a LFS file |
params.repo | RepoDesignation | - |
params.revision? | string | - |
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 | Description |
|---|---|---|
params | Object | - |
params.credentials? | Credentials | - |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> | Custom fetch function to use instead of the default one, for example to use a proxy or edit headers. |
params.hubUrl? | string | - |
params.path | string | - |
params.repo | RepoDesignation | - |
params.revision? | string | - |
Returns
Promise\<boolean>
Defined in
listDatasets
▸ listDatasets\<T>(params?): AsyncGenerator\<DatasetEntry & Pick\<ApiDatasetInfo, T>>
Type parameters
| Name | Type |
|---|---|
T | extends "description" | "author" | "cardData" | "disabled" | "gitalyUid" | "createdAt" | "tags" | "paperswithcode_id" | "sha" | "citation" | "downloadsAllTime" = never |
Parameters
| Name | Type | Description |
|---|---|---|
params? | Object | - |
params.additionalFields? | T[] | - |
params.credentials? | Credentials | - |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> | Custom fetch function to use instead of the default one, for example to use a proxy or edit headers. |
params.hubUrl? | string | - |
params.limit? | number | Set to limit the number of models returned. |
params.search? | Object | - |
params.search.owner? | string | - |
params.search.query? | string | Will search in the dataset name for matches |
params.search.tags? | string[] | - |
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 | Description |
|---|---|---|
params | Object | - |
params.credentials? | Credentials | - |
params.expand? | boolean | Fetch lastCommit and securityStatus for each file. |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> | Custom fetch function to use instead of the default one, for example to use a proxy or edit headers. |
params.hubUrl? | string | - |
params.path? | string | Eg ‘data’ for listing all files in the ‘data’ folder. Leave it empty to list all files in the repo. |
params.recursive? | boolean | Do we want to list files in subdirectories? |
params.repo | RepoDesignation | - |
params.revision? | string | - |
Returns
AsyncGenerator\<ListFileEntry>
Defined in
listModels
▸ listModels\<T>(params?): AsyncGenerator\<ModelEntry & Pick\<ApiModelInfo, T>>
Type parameters
| Name | Type |
|---|---|
T | extends "author" | "cardData" | "disabled" | "gitalyUid" | "createdAt" | "tags" | "sha" | "downloadsAllTime" | "config" | "library_name" | "spaces" | "model-index" | "safetensors" | "transformersInfo" = never |
Parameters
| Name | Type | Description |
|---|---|---|
params? | Object | - |
params.additionalFields? | T[] | - |
params.credentials? | Credentials | - |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> | Custom fetch function to use instead of the default one, for example to use a proxy or edit headers. |
params.hubUrl? | string | - |
params.limit? | number | Set to limit the number of models returned. |
params.search? | Object | - |
params.search.owner? | string | - |
params.search.query? | string | Will search in the model name for matches |
params.search.tags? | string[] | - |
params.search.task? | "text-classification" | "token-classification" | "table-question-answering" | "question-answering" | "zero-shot-classification" | "translation" | "summarization" | "feature-extraction" | "text-generation" | "text2text-generation" | "fill-mask" | "sentence-similarity" | "text-to-speech" | "text-to-audio" | "automatic-speech-recognition" | "audio-to-audio" | "audio-classification" | "voice-activity-detection" | "depth-estimation" | "image-classification" | "object-detection" | "image-segmentation" | "text-to-image" | "image-to-text" | "image-to-image" | "image-to-video" | "unconditional-image-generation" | "video-classification" | "reinforcement-learning" | "robotics" | "tabular-classification" | "tabular-regression" | "tabular-to-text" | "table-to-text" | "multiple-choice" | "text-retrieval" | "time-series-forecasting" | "text-to-video" | "image-text-to-text" | "visual-question-answering" | "document-question-answering" | "zero-shot-image-classification" | "graph-ml" | "mask-generation" | "zero-shot-object-detection" | "text-to-3d" | "image-to-3d" | "image-feature-extraction" | "other" | - |
Returns
AsyncGenerator\<ModelEntry & Pick\<ApiModelInfo, T>>
Defined in
listSpaces
▸ listSpaces\<T>(params?): AsyncGenerator\<SpaceEntry & Pick\<ApiSpaceInfo, T>>
Type parameters
| Name | Type |
|---|---|
T | extends "author" | "cardData" | "disabled" | "gitalyUid" | "createdAt" | "tags" | "sha" | "subdomain" | "runtime" | "models" | "datasets" = never |
Parameters
| Name | Type | Description |
|---|---|---|
params? | Object | - |
params.additionalFields? | T[] | Additional fields to fetch from huggingface.co. |
params.credentials? | Credentials | - |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> | Custom fetch function to use instead of the default one, for example to use a proxy or edit headers. |
params.hubUrl? | string | - |
params.search? | Object | - |
params.search.owner? | string | - |
params.search.query? | string | Will search in the space name for matches |
params.search.tags? | string[] | - |
Returns
AsyncGenerator\<SpaceEntry & Pick\<ApiSpaceInfo, T>>
Defined in
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 |
|---|---|
opts? | Object |
opts.hubUrl? | string |
Returns
Promise\<OAuthResult>
Defined in
hub/src/lib/oauth-handle-redirect.ts:42
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 |
|---|---|
opts? | Object |
opts.hubUrl? | string |
Returns
Promise\<OAuthResult | false>
Defined in
hub/src/lib/oauth-handle-redirect.ts:210
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.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 separate 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
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 | Description |
|---|---|---|
params | Object | - |
params.computeParametersCount | true | Will include SafetensorsParseFromRepo[“parameterCount”], an object containing the number of parameters for each DType Default ts false |
params.credentials? | Credentials | - |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> | Custom fetch function to use instead of the default one, for example to use a proxy or edit headers. |
params.hubUrl? | string | - |
params.path? | string | Relative file path to safetensors file inside repo. Defaults to SAFETENSORS_FILE or SAFETENSORS_INDEX_FILE (whichever one exists). |
params.repo | RepoDesignation | Only models are supported |
params.revision? | string | - |
Returns
Promise\<SetRequired\<SafetensorsParseFromRepo, "parameterCount">>
Defined in
hub/src/lib/parse-safetensors-metadata.ts:180
▸ parseSafetensorsMetadata(params): Promise\<SafetensorsParseFromRepo>
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.computeParametersCount? | boolean | - |
params.credentials? | Credentials | - |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> | Custom fetch function to use instead of the default one, for example to use a proxy or edit headers. |
params.hubUrl? | string | - |
params.path? | string | Will include SafetensorsParseFromRepo[“parameterCount”], an object containing the number of parameters for each DType Default ts false |
params.repo | RepoDesignation | Only models are supported |
params.revision? | string | - |
Returns
Promise\<SafetensorsParseFromRepo>
Defined in
hub/src/lib/parse-safetensors-metadata.ts:201
parseSafetensorsShardFile
▸ parseSafetensorsShardFile(filename): SafetensorsShardFileInfo | null
Parameters
| Name | Type |
|---|---|
filename | string |
Returns
SafetensorsShardFileInfo | null
Defined in
hub/src/lib/parse-safetensors-metadata.ts:25
uploadFile
▸ uploadFile(params): Promise\<CommitOutput>
Parameters
| Name | Type |
|---|---|
params | Object |
params.abortSignal? | AbortSignal |
params.branch? | string |
params.commitDescription? | string |
params.commitTitle? | string |
params.credentials? | Credentials |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> |
params.file | URL | File | { content: ContentSource ; path: string } |
params.hubUrl? | string |
params.isPullRequest? | boolean |
params.parentCommit? | string |
params.repo | RepoDesignation |
params.useWebWorkers? | boolean | { minSize?: number ; poolSize?: number } |
Returns
Promise\<CommitOutput>
Defined in
uploadFiles
▸ uploadFiles(params): Promise\<CommitOutput>
Parameters
| Name | Type |
|---|---|
params | Object |
params.abortSignal? | AbortSignal |
params.branch? | string |
params.commitDescription? | string |
params.commitTitle? | string |
params.credentials? | Credentials |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> |
params.files | (URL | File | { content: ContentSource ; path: string })[] |
params.hubUrl? | string |
params.isPullRequest? | boolean |
params.parentCommit? | string |
params.repo | RepoDesignation |
params.useWebWorkers? | boolean | { minSize?: number ; poolSize?: number } |
Returns
Promise\<CommitOutput>
Defined in
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 | Description |
|---|---|---|
params | Object | - |
params.abortSignal? | AbortSignal | - |
params.branch? | string | - |
params.commitDescription? | string | - |
params.commitTitle? | string | - |
params.credentials? | Credentials | - |
params.files | (URL | File | { content: ContentSource ; path: string })[] | - |
params.hubUrl? | string | - |
params.isPullRequest? | boolean | - |
params.parentCommit? | string | - |
params.repo | RepoDesignation | - |
params.useWebWorkers? | boolean | { minSize?: number ; poolSize?: number } | Set this to true in order to have progress events for hashing |
Returns
AsyncGenerator\<CommitProgressEvent, CommitOutput>
Defined in
hub/src/lib/upload-files-with-progress.ts:19
whoAmI
▸ whoAmI(params): Promise\<WhoAmI & { auth: AuthInfo }>
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | - |
params.credentials | Credentials | - |
params.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise\<Response>(input: string | URL | Request, init?: RequestInit) => Promise\<Response> | Custom fetch function to use instead of the default one, for example to use a proxy or edit headers. |
params.hubUrl? | string | - |
Returns
Promise\<WhoAmI & { auth: AuthInfo }>