命令行界面 (CLI)

huggingface_hub Python 包附带了一个内置的 CLI，称为 huggingface-cli。此工具允许您直接从终端与 Hugging Face Hub 交互。例如，您可以登录您的帐户，创建代码库，上传和下载文件等。它还附带了用于配置您的机器或管理缓存的便捷功能。在本指南中，我们将了解 CLI 的主要功能以及如何使用它们。

开始使用

首先，让我们安装 CLI

>>> pip install -U "huggingface_hub[cli]"

在上面的代码段中，我们还安装了 [cli] 额外依赖项以改善用户体验，尤其是在使用 delete-cache 命令时。

安装完成后，您可以检查 CLI 是否已正确设置

>>> huggingface-cli --help
usage: huggingface-cli <command> [<args>]

positional arguments:
  {env,login,whoami,logout,repo,upload,download,lfs-enable-largefiles,lfs-multipart-upload,scan-cache,delete-cache,tag}
                        huggingface-cli command helpers
    env                 Print information about the environment.
    login               Log in using a token from huggingface.co/settings/tokens
    whoami              Find out which huggingface.co account you are logged in as.
    logout              Log out
    repo                {create} Commands to interact with your huggingface.co repos.
    upload              Upload a file or a folder to a repo on the Hub
    download            Download files from the Hub
    lfs-enable-largefiles
                        Configure your repository to enable upload of files > 5GB.
    scan-cache          Scan cache directory.
    delete-cache        Delete revisions from the cache directory.
    tag                 (create, list, delete) tags for a repo in the hub

options:
  -h, --help            show this help message and exit

如果 CLI 正确安装，您应该会看到 CLI 中所有可用选项的列表。如果您收到错误消息，例如 command not found: huggingface-cli，请参阅安装指南。

--help 选项非常方便，可以获取有关命令的更多详细信息。您可以随时使用它来列出所有可用选项及其详细信息。例如，huggingface-cli upload --help 提供了有关如何使用 CLI 上传文件的更多信息。

备用安装

使用 Pkgx

Pkgx 是一款超快的跨平台包管理器，可以运行任何程序。您可以使用 pkgx 如下安装 huggingface-cli

>>> pkgx install huggingface-cli

或者您可以直接运行 huggingface-cli

>>> pkgx huggingface-cli --help

查看 pkgx huggingface 页面此处以获取更多详细信息。

使用 Homebrew

您还可以使用 Homebrew 安装 CLI

>>> brew install huggingface-cli

查看 Homebrew huggingface 页面此处以获取更多详细信息。

huggingface-cli 登录

在许多情况下，您必须登录到 Hugging Face 帐户才能与 Hub 交互（下载私有存储库、上传文件、创建 PR 等）。为此，您需要从您的设置页面获取用户访问令牌。用户访问令牌用于向 Hub 验证您的身份。如果您想上传或修改内容，请确保设置具有写入权限的令牌。

获得令牌后，在您的终端中运行以下命令

>>> huggingface-cli login

此命令将提示您输入令牌。复制粘贴您的令牌并按Enter键。然后，系统会询问您是否也应将令牌保存为 git 凭据。如果您计划在本地使用git，请再次按Enter键（默认为是）。最后，它将调用 Hub 以检查您的令牌是否有效并将其保存在本地。

_|    _|  _|    _|    _|_|_|    _|_|_|  _|_|_|  _|      _|    _|_|_|      _|_|_|_|    _|_|      _|_|_|  _|_|_|_|
_|    _|  _|    _|  _|        _|          _|    _|_|    _|  _|            _|        _|    _|  _|        _|
_|_|_|_|  _|    _|  _|  _|_|  _|  _|_|    _|    _|  _|  _|  _|  _|_|      _|_|_|    _|_|_|_|  _|        _|_|_|
_|    _|  _|    _|  _|    _|  _|    _|    _|    _|    _|_|  _|    _|      _|        _|    _|  _|        _|
_|    _|    _|_|      _|_|_|    _|_|_|  _|_|_|  _|      _|    _|_|_|      _|        _|    _|    _|_|_|  _|_|_|_|

To log in, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens .
Enter your token (input will not be visible):
Add token as git credential? (Y/n)
Token is valid (permission: write).
Your token has been saved in your configured git credential helpers (store).
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful

或者，如果您想在不提示的情况下登录，可以从命令行直接传递令牌。为了更安全，我们建议将您的令牌作为环境变量传递，以避免将其粘贴到您的命令历史记录中。

# Or using an environment variable
>>> huggingface-cli login --token $HF_TOKEN --add-to-git-credential
Token is valid (permission: write).
The token `token_name` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved in your configured git credential helpers (store).
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful
The current active token is: `token_name`

有关身份验证的更多详细信息，请查看此部分。

huggingface-cli whoami

如果您想知道是否已登录，可以使用huggingface-cli whoami。此命令没有任何选项，只需打印您的用户名以及您在 Hub 中所属的组织

huggingface-cli whoami
Wauplin
orgs:  huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster

如果您未登录，将打印错误消息。

huggingface-cli 注销

此命令将您注销。实际上，它将删除您机器上存储的所有令牌。如果您想删除特定令牌，可以将令牌名称指定为参数。

如果您使用HF_TOKEN环境变量登录（请参阅参考），则此命令不会将您注销。如果是这种情况，您必须在您的机器配置中取消设置环境变量。

huggingface-cli 下载

使用huggingface-cli download命令直接从 Hub 下载文件。在内部，它使用hf_hub_download()和snapshot_download()辅助函数（在下载指南中描述），并将返回路径打印到终端。在下面的示例中，我们将逐步介绍最常见的用例。有关可用选项的完整列表，您可以运行

huggingface-cli download --help

下载单个文件

要从存储库下载单个文件，只需提供 repo_id 和文件名，如下所示

>>> huggingface-cli download gpt2 config.json
downloading https://huggingface.co/gpt2/resolve/main/config.json to /home/wauplin/.cache/huggingface/hub/tmpwrq8dm5o
(…)ingface.co/gpt2/resolve/main/config.json: 100%|██████████████████████████████████| 665/665 [00:00<00:00, 2.49MB/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

该命令始终会在最后一行打印文件在您本地计算机上的路径。

下载整个存储库

在某些情况下，您只想下载存储库中的所有文件。这可以通过仅指定存储库 ID 来完成

>>> huggingface-cli download HuggingFaceH4/zephyr-7b-beta
Fetching 23 files:   0%|                                                | 0/23 [00:00<?, ?it/s]
...
...
/home/wauplin/.cache/huggingface/hub/models--HuggingFaceH4--zephyr-7b-beta/snapshots/3bac358730f8806e5c3dc7c7e19eb36e045bf720

下载多个文件

您还可以使用单个命令下载存储库中的一部分文件。这可以通过两种方式完成。如果您已经拥有要下载的文件的精确列表，则可以简单地按顺序提供它们

>>> huggingface-cli download gpt2 config.json model.safetensors
Fetching 2 files:   0%|                                                                        | 0/2 [00:00<?, ?it/s]
downloading https://huggingface.co/gpt2/resolve/11c5a3d5811f50298f278a704980280950aedb10/model.safetensors to /home/wauplin/.cache/huggingface/hub/tmpdachpl3o
(…)8f278a7049802950aedb10/model.safetensors: 100%|██████████████████████████████| 8.09k/8.09k [00:00<00:00, 40.5MB/s]
Fetching 2 files: 100%|████████████████████████████████████████████████████████████████| 2/2 [00:00<00:00,  3.76it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10

另一种方法是使用--include和--exclude提供模式来过滤要下载的文件。例如，如果您想从stabilityai/stable-diffusion-xl-base-1.0下载所有 safetensors 文件，但 FP16 精度的文件除外

>>> huggingface-cli download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"*
Fetching 8 files:   0%|                                                                         | 0/8 [00:00<?, ?it/s]
...
...
Fetching 8 files: 100%|█████████████████████████████████████████████████████████████████████████| 8/8 (...)
/home/wauplin/.cache/huggingface/hub/models--stabilityai--stable-diffusion-xl-base-1.0/snapshots/462165984030d82259a11f4367a4eed129e94a7b

下载数据集或空间

以上示例展示了如何从模型仓库下载。要下载数据集或空间，请使用--repo-type选项

# https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k
>>> huggingface-cli download HuggingFaceH4/ultrachat_200k --repo-type dataset

# https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat
>>> huggingface-cli download HuggingFaceH4/zephyr-chat --repo-type space

...

下载特定版本

以上示例展示了如何从主分支的最新提交下载。要从特定版本（提交哈希值、分支名称或标签）下载，请使用--revision选项

>>> huggingface-cli download bigcode/the-stack --repo-type dataset --revision v1.1
...

下载到本地文件夹

从 Hub 下载文件的推荐（也是默认）方式是使用缓存系统。但是，在某些情况下，您可能希望下载文件并将其移动到特定文件夹。这对于使工作流程更接近 git 命令提供的功能很有用。您可以使用--local-dir选项来实现。

在本地目录的根目录下会创建一个.cache/huggingface/文件夹，其中包含有关下载文件的元数据。如果文件已经是最新版本，则可以防止重新下载文件。如果元数据已更改，则会下载新文件版本。这使得local-dir能够优化仅提取最新更改。

有关如何将文件下载到本地文件的更多详细信息，请查看下载指南。

>>> huggingface-cli download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu
...
fuyu/model-00001-of-00002.safetensors

指定缓存目录

如果不使用--local-dir，则默认情况下所有文件都将下载到由HF_HOME环境变量定义的缓存目录。您可以使用--cache-dir指定自定义缓存

>>> huggingface-cli download adept/fuyu-8b --cache-dir ./path/to/cache
...
./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745

指定令牌

要访问私有或受限仓库，必须使用令牌。默认情况下，将使用本地保存的令牌（使用huggingface-cli login）。如果要显式进行身份验证，请使用--token选项

>>> huggingface-cli download gpt2 config.json --token=hf_****
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

静默模式

默认情况下，huggingface-cli download命令将非常详细。它将打印详细信息，例如警告消息、有关下载文件的信息和进度条。如果要取消所有这些，请使用--quiet选项。仅打印最后一行（即下载文件的路径）。如果要在脚本中将输出传递给另一个命令，这将非常有用。

>>> huggingface-cli download gpt2 --quiet
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10

下载超时

在网络连接缓慢的机器上，您可能会遇到如下所示的超时问题

`requests.exceptions.ReadTimeout: (ReadTimeoutError("HTTPSConnectionPool(host='cdn-lfs-us-1.huggingface.co', port=443): Read timed out. (read timeout=10)"), '(Request ID: a33d910c-84c6-4514-8362-c705e2039d38)')`

要缓解此问题，可以将HF_HUB_DOWNLOAD_TIMEOUT环境变量设置为更高的值（默认值为 10）

export HF_HUB_DOWNLOAD_TIMEOUT=30

有关更多详细信息，请查看环境变量参考。并重新运行您的下载命令。

huggingface-cli upload

使用huggingface-cli upload命令将文件直接上传到 Hub。在内部，它使用upload_file()和upload_folder()帮助程序（在上传指南中进行了描述）。在下面的示例中，我们将逐步介绍最常见的用例。有关可用选项的完整列表，您可以运行

>>> huggingface-cli upload --help

上传整个文件夹

此命令的默认用法是

# Usage:  huggingface-cli upload [repo_id] [local_path] [path_in_repo]

>>> huggingface-cli upload my-cool-model . .
https://huggingface.co/Wauplin/my-cool-model/tree/main/

如果仓库尚不存在，它将自动创建。

您还可以上传特定文件夹

>>> huggingface-cli upload my-cool-model ./models .
https://huggingface.co/Wauplin/my-cool-model/tree/main/

最后，您可以将文件夹上传到仓库上的特定目标位置

>>> huggingface-cli upload my-cool-model ./path/to/curated/data /data/train
https://huggingface.co/Wauplin/my-cool-model/tree/main/data/train

上传单个文件

您还可以通过将local_path设置为指向您机器上的文件来上传单个文件。如果是这种情况，path_in_repo是可选的，并将默认为您本地文件的名称

>>> huggingface-cli upload Wauplin/my-cool-model ./models/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors

如果要将单个文件上传到特定目录，请相应地设置path_in_repo

>>> huggingface-cli upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensors

上传多个文件

要一次性上传文件夹中的多个文件而不上传整个文件夹，请使用--include和--exclude模式。它还可以与--delete选项结合使用，以便在上传新文件时删除存储库中的文件。在下面的示例中，我们通过删除远程文件并上传除/logs中的文件之外的所有文件来同步本地空间。

# Sync local Space with Hub (upload new files except from logs/, delete removed files)
>>> huggingface-cli upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"
...

上传到数据集或空间

要上传到数据集或空间，请使用--repo-type选项。

>>> huggingface-cli upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset
...

上传到组织

要将内容上传到组织拥有的存储库而不是个人存储库，您必须在repo_id中明确指定它。

>>> huggingface-cli upload MyCoolOrganization/my-cool-model . .
https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/

上传到特定修订版

默认情况下，文件会上传到main分支。如果要将文件上传到其他分支或引用，请使用--revision选项。

# Upload files to a PR
>>> huggingface-cli upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...

注意：如果revision不存在且未设置--create-pr，则将从main分支自动创建分支。

上传并创建PR

如果您没有权限推送到存储库，则必须打开PR并让作者了解您想要进行的更改。这可以通过设置--create-pr选项来完成。

# Create a PR and upload the files to it
>>> huggingface-cli upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/

定期上传

在某些情况下，您可能希望定期将更新推送到存储库。例如，如果您正在训练模型并希望每 10 分钟上传一次日志文件夹，这将非常有用。您可以使用--every选项执行此操作。

# Upload new logs every 10 minutes
huggingface-cli upload training-model logs/ --every=10

指定提交消息

使用--commit-message和--commit-description为您的提交设置自定义消息和描述，而不是默认消息和描述。

>>> huggingface-cli upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%. Check tensorboard for more details."
...
https://huggingface.co/Wauplin/my-cool-model/tree/main

指定令牌

要上传文件，您必须使用令牌。默认情况下，将使用本地保存的令牌（使用huggingface-cli login）。如果要显式进行身份验证，请使用--token选项。

>>> huggingface-cli upload Wauplin/my-cool-model ./models . --token=hf_****
...
https://huggingface.co/Wauplin/my-cool-model/tree/main

静默模式

默认情况下，huggingface-cli upload命令将非常详细。它将打印详细信息，例如警告消息、有关上传文件的信息和进度条。如果要取消所有这些内容，请使用--quiet选项。仅打印最后一行（即上传文件的 URL）。如果您想在脚本中将输出传递给另一个命令，这将非常有用。

>>> huggingface-cli upload Wauplin/my-cool-model ./models . --quiet
https://huggingface.co/Wauplin/my-cool-model/tree/main

huggingface-cli repo-files

如果要从 Hugging Face 存储库中删除文件，请使用huggingface-cli repo-files命令。

删除文件

huggingface-cli repo-files <repo_id> delete子命令允许您从存储库中删除文件。以下是一些使用示例。

删除文件夹

>>> huggingface-cli repo-files Wauplin/my-cool-model delete folder/
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...

删除多个文件

>>> huggingface-cli repo-files Wauplin/my-cool-model delete file.txt folder/pytorch_model.bin
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...

使用类 Unix 通配符删除一组文件

>>> huggingface-cli repo-files Wauplin/my-cool-model delete "*.txt" "folder/*.bin"
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...

指定令牌

要从存储库中删除文件，您必须经过身份验证和授权。默认情况下，将使用本地保存的令牌（使用huggingface-cli login）。如果要显式进行身份验证，请使用--token选项。

>>> huggingface-cli repo-files --token=hf_**** Wauplin/my-cool-model delete file.txt

huggingface-cli scan-cache

扫描缓存目录对于了解您已下载了哪些存储库以及它在磁盘上占用了多少空间很有用。您可以通过运行huggingface-cli scan-cache来执行此操作。

>>> huggingface-cli scan-cache
REPO ID                     REPO TYPE SIZE ON DISK NB FILES LAST_ACCESSED LAST_MODIFIED REFS                LOCAL PATH
--------------------------- --------- ------------ -------- ------------- ------------- ------------------- -------------------------------------------------------------------------
glue                        dataset         116.3K       15 4 days ago    4 days ago    2.4.0, main, 1.17.0 /home/wauplin/.cache/huggingface/hub/datasets--glue
google/fleurs               dataset          64.9M        6 1 week ago    1 week ago    refs/pr/1, main     /home/wauplin/.cache/huggingface/hub/datasets--google--fleurs
Jean-Baptiste/camembert-ner model           441.0M        7 2 weeks ago   16 hours ago  main                /home/wauplin/.cache/huggingface/hub/models--Jean-Baptiste--camembert-ner
bert-base-cased             model             1.9G       13 1 week ago    2 years ago                       /home/wauplin/.cache/huggingface/hub/models--bert-base-cased
t5-base                     model            10.1K        3 3 months ago  3 months ago  main                /home/wauplin/.cache/huggingface/hub/models--t5-base
t5-small                    model           970.7M       11 3 days ago    3 days ago    refs/pr/1, main     /home/wauplin/.cache/huggingface/hub/models--t5-small

Done in 0.0s. Scanned 6 repo(s) for a total of 3.4G.
Got 1 warning(s) while scanning. Use -vvv to print details.

有关如何扫描缓存目录的更多详细信息，请参阅管理您的缓存指南。

huggingface-cli delete-cache

huggingface-cli delete-cache 是一个帮助您删除不再使用的缓存部分的工具。这对于节省和释放磁盘空间非常有用。要了解有关使用此命令的更多信息，请参阅管理缓存指南。

huggingface-cli tag

huggingface-cli tag 命令允许您为存储库添加标签、取消标签和列出标签。

为模型添加标签

要为存储库添加标签，您需要提供repo_id和tag名称。

>>> huggingface-cli tag Wauplin/my-cool-model v1.0
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-model

在特定版本上为模型添加标签

如果要为特定版本添加标签，可以使用--revision选项。默认情况下，标签将在main分支上创建。

>>> huggingface-cli tag Wauplin/my-cool-model v1.0 --revision refs/pr/104
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-model

为数据集或Space添加标签

如果要为数据集或Space添加标签，必须指定--repo-type选项。

>>> huggingface-cli tag bigcode/the-stack v1.0 --repo-type dataset
You are about to create tag v1.0 on dataset bigcode/the-stack
Tag v1.0 created on bigcode/the-stack

列出标签

要列出存储库的所有标签，请使用-l或--list选项。

>>> huggingface-cli tag Wauplin/gradio-space-ci -l --repo-type space
Tags for space Wauplin/gradio-space-ci:
0.2.2
0.2.1
0.2.0
0.1.2
0.0.2
0.0.1

删除标签

要删除标签，请使用-d或--delete选项。

>>> huggingface-cli tag -d Wauplin/my-cool-model v1.0
You are about to delete tag v1.0 on model Wauplin/my-cool-model
Proceed? [Y/n] y
Tag v1.0 deleted on Wauplin/my-cool-model

您还可以传递-y跳过确认步骤。

huggingface-cli env

huggingface-cli env 命令打印有关您的机器设置的详细信息。当您在GitHub上打开问题以帮助维护者调查您的问题时，这很有用。

>>> huggingface-cli env

Copy-and-paste the text below in your GitHub issue.

- huggingface_hub version: 0.19.0.dev0
- Platform: Linux-6.2.0-36-generic-x86_64-with-glibc2.35
- Python version: 3.10.12
- Running in iPython ?: No
- Running in notebook ?: No
- Running in Google Colab ?: No
- Token path ?: /home/wauplin/.cache/huggingface/token
- Has saved token ?: True
- Who am I ?: Wauplin
- Configured git credential helpers: store
- FastAI: N/A
- Tensorflow: 2.11.0
- Torch: 1.12.1
- Jinja2: 3.1.2
- Graphviz: 0.20.1
- Pydot: 1.4.2
- Pillow: 9.2.0
- hf_transfer: 0.1.3
- gradio: 4.0.2
- tensorboard: 2.6
- numpy: 1.23.2
- pydantic: 2.4.2
- aiohttp: 3.8.4
- ENDPOINT: https://huggingface.co
- HF_HUB_CACHE: /home/wauplin/.cache/huggingface/hub
- HF_ASSETS_CACHE: /home/wauplin/.cache/huggingface/assets
- HF_TOKEN_PATH: /home/wauplin/.cache/huggingface/token
- HF_HUB_OFFLINE: False
- HF_HUB_DISABLE_TELEMETRY: False
- HF_HUB_DISABLE_PROGRESS_BARS: None
- HF_HUB_DISABLE_SYMLINKS_WARNING: False
- HF_HUB_DISABLE_EXPERIMENTAL_WARNING: False
- HF_HUB_DISABLE_IMPLICIT_TOKEN: False
- HF_HUB_ENABLE_HF_TRANSFER: False
- HF_HUB_ETAG_TIMEOUT: 10
- HF_HUB_DOWNLOAD_TIMEOUT: 10

< > 更新在GitHub上

Hub Python 库

命令行界面 (CLI)

开始使用

备用安装

使用 Pkgx

使用 Homebrew

huggingface-cli 登录

huggingface-cli whoami

huggingface-cli 注销

huggingface-cli 下载

下载单个文件

下载整个存储库

下载多个文件

下载数据集或空间

下载特定版本

下载到本地文件夹

指定缓存目录

指定令牌

静默模式

下载超时

huggingface-cli upload

上传整个文件夹

上传单个文件

上传多个文件

上传到数据集或空间

上传到组织

上传到特定修订版

上传并创建PR

定期上传

指定提交消息

指定令牌

静默模式

huggingface-cli repo-files

删除文件

指定令牌

huggingface-cli scan-cache

huggingface-cli delete-cache

huggingface-cli tag

为模型添加标签

在特定版本上为模型添加标签

为数据集或Space添加标签

列出标签

删除标签

huggingface-cli env