hugging-face-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hugging Face CLI

The

hf

CLI provides direct terminal access to the Hugging Face Hub for downloading, uploading, and managing repositories, cache, and compute resources.

hf

CLI 提供了对Hugging Face Hub的终端直接访问权限，可用于下载、上传和管理仓库、缓存及计算资源。

Quick Command Reference

快速命令参考

Task	Command
Login	`hf auth login`
Download model	`hf download <repo_id>`
Download to folder	`hf download <repo_id> --local-dir ./path`
Upload folder	`hf upload <repo_id> . .`
Create repo	`hf repo create <name>`
Create tag	`hf repo tag create <repo_id> <tag>`
Delete files	`hf repo-files delete <repo_id> <files>`
List cache	`hf cache ls`
Remove from cache	`hf cache rm <repo_or_revision>`
List models	`hf models ls`
Get model info	`hf models info <model_id>`
List datasets	`hf datasets ls`
Get dataset info	`hf datasets info <dataset_id>`
List spaces	`hf spaces ls`
Get space info	`hf spaces info <space_id>`
List endpoints	`hf endpoints ls`
Run GPU job	`hf jobs run --flavor a10g-small <image> <cmd>`
Environment info	`hf env`

任务	命令
登录	`hf auth login`
下载模型	`hf download <repo_id>`
下载到指定文件夹	`hf download <repo_id> --local-dir ./path`
上传文件夹	`hf upload <repo_id> . .`
创建仓库	`hf repo create <name>`
创建标签	`hf repo tag create <repo_id> <tag>`
删除文件	`hf repo-files delete <repo_id> <files>`
列出缓存内容	`hf cache ls`
从缓存中移除	`hf cache rm <repo_or_revision>`
列出模型	`hf models ls`
获取模型信息	`hf models info <model_id>`
列出数据集	`hf datasets ls`
获取数据集信息	`hf datasets info <dataset_id>`
列出Spaces	`hf spaces ls`
获取Space信息	`hf spaces info <space_id>`
列出端点	`hf endpoints ls`
运行GPU任务	`hf jobs run --flavor a10g-small <image> <cmd>`
环境信息	`hf env`

Core Commands

核心命令

Authentication

身份验证

bash

hf auth login                    # Interactive login
hf auth login --token $HF_TOKEN  # Non-interactive
hf auth whoami                   # Check current user
hf auth list                     # List stored tokens
hf auth switch                   # Switch between tokens
hf auth logout                   # Log out

bash

hf auth login                    # 交互式登录
hf auth login --token $HF_TOKEN  # 非交互式登录
hf auth whoami                   # 查看当前用户
hf auth list                     # 列出存储的令牌
hf auth switch                   # 切换令牌
hf auth logout                   # 登出

Download

下载

bash

hf download <repo_id>                              # Full repo to cache
hf download <repo_id> file.safetensors             # Specific file
hf download <repo_id> --local-dir ./models         # To local directory
hf download <repo_id> --include "*.safetensors"    # Filter by pattern
hf download <repo_id> --repo-type dataset          # Dataset
hf download <repo_id> --revision v1.0              # Specific version

bash

hf download <repo_id>                              # 将整个仓库下载到缓存
hf download <repo_id> file.safetensors             # 下载指定文件
hf download <repo_id> --local-dir ./models         # 下载到本地目录
hf download <repo_id> --include "*.safetensors"    # 按规则过滤文件
hf download <repo_id> --repo-type dataset          # 下载数据集
hf download <repo_id> --revision v1.0              # 下载指定版本

Upload

上传

bash

hf upload <repo_id> . .                            # Current dir to root
hf upload <repo_id> ./models /weights              # Folder to path
hf upload <repo_id> model.safetensors              # Single file
hf upload <repo_id> . . --repo-type dataset        # Dataset
hf upload <repo_id> . . --create-pr                # Create PR
hf upload <repo_id> . . --commit-message="msg"     # Custom message

bash

hf upload <repo_id> . .                            # 将当前目录上传到仓库根目录
hf upload <repo_id> ./models /weights              # 将本地文件夹上传到指定路径
hf upload <repo_id> model.safetensors              # 上传单个文件
hf upload <repo_id> . . --repo-type dataset        # 上传数据集
hf upload <repo_id> . . --create-pr                # 创建Pull Request
hf upload <repo_id> . . --commit-message="msg"     # 自定义提交信息

Repository Management

仓库管理

bash

hf repo create <name>                              # Create model repo
hf repo create <name> --repo-type dataset          # Create dataset
hf repo create <name> --private                    # Private repo
hf repo create <name> --repo-type space --space_sdk gradio  # Gradio space
hf repo delete <repo_id>                           # Delete repo
hf repo move <from_id> <to_id>                     # Move repo to new namespace
hf repo settings <repo_id> --private true          # Update repo settings
hf repo list --repo-type model                     # List repos
hf repo branch create <repo_id> release-v1         # Create branch
hf repo branch delete <repo_id> release-v1         # Delete branch
hf repo tag create <repo_id> v1.0                  # Create tag
hf repo tag list <repo_id>                         # List tags
hf repo tag delete <repo_id> v1.0                  # Delete tag

bash

hf repo create <name>                              # 创建模型仓库
hf repo create <name> --repo-type dataset          # 创建数据集仓库
hf repo create <name> --private                    # 创建私有仓库
hf repo create <name> --repo-type space --space_sdk gradio  # 创建Gradio Space
hf repo delete <repo_id>                           # 删除仓库
hf repo move <from_id> <to_id>                     # 将仓库移动到新命名空间
hf repo settings <repo_id> --private true          # 更新仓库设置
hf repo list --repo-type model                     # 列出仓库
hf repo branch create <repo_id> release-v1         # 创建分支
hf repo branch delete <repo_id> release-v1         # 删除分支
hf repo tag create <repo_id> v1.0                  # 创建标签
hf repo tag list <repo_id>                         # 列出标签
hf repo tag delete <repo_id> v1.0                  # 删除标签

Delete Files from Repo

从仓库中删除文件

bash

hf repo-files delete <repo_id> folder/             # Delete folder
hf repo-files delete <repo_id> "*.txt"             # Delete with pattern

bash

hf repo-files delete <repo_id> folder/             # 删除文件夹
hf repo-files delete <repo_id> "*.txt"             # 按规则删除文件

Cache Management

缓存管理

bash

hf cache ls                      # List cached repos
hf cache ls --revisions          # Include individual revisions
hf cache rm model/gpt2           # Remove cached repo
hf cache rm <revision_hash>      # Remove cached revision
hf cache prune                   # Remove detached revisions
hf cache verify gpt2             # Verify checksums from cache

bash

hf cache ls                      # 列出已缓存的仓库
hf cache ls --revisions          # 包含单个版本信息
hf cache rm model/gpt2           # 移除已缓存的仓库
hf cache rm <revision_hash>      # 移除已缓存的版本
hf cache prune                   # 移除孤立的版本
hf cache verify gpt2             # 验证缓存中的校验和

Browse Hub

浏览Hub

bash

undefined

bash

undefined

Models

模型

hf models ls # List top trending models hf models ls --search "MiniMax" --author MiniMaxAI # Search models hf models ls --filter "text-generation" --limit 20 # Filter by task hf models info MiniMaxAI/MiniMax-M2.1 # Get model info

hf models ls # 列出热门模型 hf models ls --search "MiniMax" --author MiniMaxAI # 搜索模型 hf models ls --filter "text-generation" --limit 20 # 按任务过滤模型 hf models info MiniMaxAI/MiniMax-M2.1 # 获取模型详情

Datasets

数据集

hf datasets ls # List top trending datasets hf datasets ls --search "finepdfs" --sort downloads # Search datasets hf datasets info HuggingFaceFW/finepdfs # Get dataset info

hf datasets ls # 列出热门数据集 hf datasets ls --search "finepdfs" --sort downloads # 搜索数据集 hf datasets info HuggingFaceFW/finepdfs # 获取数据集详情

Spaces

hf spaces ls # List top trending spaces hf spaces ls --filter "3d" --limit 10 # Filter by 3D modeling spaces hf spaces info enzostvs/deepsite # Get space info

undefined

hf spaces ls # 列出热门Spaces hf spaces ls --filter "3d" --limit 10 # 按3D建模过滤Spaces hf spaces info enzostvs/deepsite # 获取Space详情

undefined

Jobs (Cloud Compute)

任务（云计算）

bash

hf jobs run python:3.12 python script.py           # Run on CPU
hf jobs run --flavor a10g-small <image> <cmd>      # Run on GPU
hf jobs run --secrets HF_TOKEN <image> <cmd>       # With HF token
hf jobs ps                                         # List jobs
hf jobs logs <job_id>                              # View logs
hf jobs cancel <job_id>                            # Cancel job

bash

hf jobs run python:3.12 python script.py           # 在CPU上运行任务
hf jobs run --flavor a10g-small <image> <cmd>      # 在GPU上运行任务
hf jobs run --secrets HF_TOKEN <image> <cmd>       # 使用HF令牌运行任务
hf jobs ps                                         # 列出任务
hf jobs logs <job_id>                              # 查看任务日志
hf jobs cancel <job_id>                            # 取消任务

Inference Endpoints

推理端点

bash

hf endpoints ls                                     # List endpoints
hf endpoints deploy my-endpoint \
  --repo openai/gpt-oss-120b \
  --framework vllm \
  --accelerator gpu \
  --instance-size x4 \
  --instance-type nvidia-a10g \
  --region us-east-1 \
  --vendor aws
hf endpoints describe my-endpoint                   # Show endpoint details
hf endpoints pause my-endpoint                      # Pause endpoint
hf endpoints resume my-endpoint                     # Resume endpoint
hf endpoints scale-to-zero my-endpoint              # Scale to zero
hf endpoints delete my-endpoint --yes               # Delete endpoint

GPU Flavors:

cpu-basic

cpu-upgrade

cpu-xl

t4-small

t4-medium

l4x1

l4x4

l40sx1

l40sx4

l40sx8

a10g-small

a10g-large

a10g-largex2

a10g-largex4

a100-large

h100

h100x8

bash

hf endpoints ls                                     # 列出端点
hf endpoints deploy my-endpoint \
  --repo openai/gpt-oss-120b \
  --framework vllm \
  --accelerator gpu \
  --instance-size x4 \
  --instance-type nvidia-a10g \
  --region us-east-1 \
  --vendor aws
hf endpoints describe my-endpoint                   # 查看端点详情
hf endpoints pause my-endpoint                      # 暂停端点
hf endpoints resume my-endpoint                     # 恢复端点
hf endpoints scale-to-zero my-endpoint              # 缩容至零实例
hf endpoints delete my-endpoint --yes               # 删除端点

GPU规格：

cpu-basic

cpu-upgrade

cpu-xl

t4-small

t4-medium

l4x1

l4x4

l40sx1

l40sx4

l40sx8

a10g-small

a10g-large

a10g-largex2

a10g-largex4

a100-large

h100

h100x8

Common Patterns

常见使用模式

Download and Use Model Locally

下载模型并本地使用

bash

undefined

bash

undefined

Download to local directory for deployment

下载到本地目录用于部署

hf download meta-llama/Llama-3.2-1B-Instruct --local-dir ./model

Or use cache and get path

或使用缓存并获取路径

MODEL_PATH=$(hf download meta-llama/Llama-3.2-1B-Instruct --quiet)

undefined

MODEL_PATH=$(hf download meta-llama/Llama-3.2-1B-Instruct --quiet)

undefined

Publish Model/Dataset

发布模型/数据集

bash

hf repo create my-username/my-model --private
hf upload my-username/my-model ./output . --commit-message="Initial release"
hf repo tag create my-username/my-model v1.0

bash

hf repo create my-username/my-model --private
hf upload my-username/my-model ./output . --commit-message="Initial release"
hf repo tag create my-username/my-model v1.0

Sync Space with Local

同步Space与本地内容

bash

hf upload my-username/my-space . . --repo-type space \
  --exclude="logs/*" --delete="*" --commit-message="Sync"

bash

hf upload my-username/my-space . . --repo-type space \
  --exclude="logs/*" --delete="*" --commit-message="Sync"

Check Cache Usage

检查缓存使用情况

bash

hf cache ls                      # See all cached repos and sizes
hf cache rm model/gpt2           # Remove a repo from cache

bash

hf cache ls                      # 查看所有缓存仓库及大小
hf cache rm model/gpt2           # 从缓存中移除指定仓库

Key Options

关键选项

```
--repo-type
```
:
```
model
```
(default),
```
dataset
```
,
```
space
```
```
--revision
```
: Branch, tag, or commit hash
```
--token
```
: Override authentication
```
--quiet
```
: Output only essential info (paths/URLs)

```
--repo-type
```
：
```
model
```
（默认）、
```
dataset
```
、
```
space
```
```
--revision
```
：分支、标签或提交哈希
```
--token
```
：覆盖身份验证令牌
```
--quiet
```
：仅输出必要信息（路径/URL）

References

参考资料

Complete command reference: See references/commands.md
Workflow examples: See references/examples.md

完整命令参考：查看 references/commands.md
工作流示例：查看 references/examples.md