命令行界面

diffusers-cli 是一个命令行客户端，用于运行、检查和打包 Diffusers 流水线。

可用命令

此页面未列出每个子命令下的所有选项。要查看任意子命令的完整且始终最新的选项列表，请运行 diffusers-cli <command> --help（diffusers-cli run --help）。

env

打印 Python、PyTorch、Diffusers 的版本、CUDA 信息以及已安装的可选依赖项。在提交 issue 时使用它，以便维护者能够复现你的环境配置。

diffusers-cli env

模式

返回该 pipeline 所接受的输入，而无需下载权重。在构建 run 的 --pipeline-kwargs 时使用它。

仅会获取索引文件。标准流水线读取 model_index.json。模块化流水线读取 modular_model_index.json。自定义块仓库读取 modular_config.json，并且需要 --trust-remote-code，因为加载它们会执行 Hub 代码。

diffusers-cli --format json schema --model black-forest-labs/FLUX.1-dev
diffusers-cli schema --model my-org/my-custom-blocks --trust-remote-code

运行

端到端运行流水线。CLI 会自动检测标准仓库与模块化仓库。它会自动从 URL 或本地路径加载媒体输入，根据流水线的返回类型保存输出，并可通过 --remote 在 Hugging Face Sandbox 上远程运行。

最小示例：

diffusers-cli run \
    --model black-forest-labs/FLUX.1-dev \
    --dtype bf16 \
    --pipeline-kwargs '{"prompt": "an astronaut riding a horse"}'

传递 pipeline 参数

--pipeline-kwargs 接受一个 JSON 对象，并将其转发给 pipeline(**kwargs)。位于已知媒体输入键处的字符串值会自动加载：

• 图像（image、last_image、mask_image、control_image、ip_adapter_image、image_2）→ 通过 load_image 转换为 PIL.Image。
• 视频（video、control_video）→ 通过 load_video 转换为 list[PIL.Image]。
• 音频（initial_audio_waveforms、reference_audio、src_audio）→ 通过 torchaudio.load 转换为 torch.Tensor。

diffusers-cli run \
    --model black-forest-labs/FLUX.2-klein-9B --dtype bf16 \
    --pipeline-kwargs '{"prompt": "make the fur grey", "image": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png", "strength": 0.6}'

媒体键和文本键均接受 JSON 数组，以便通过单次 pipeline 调用执行批量处理。媒体列表中的每个条目都会单独加载（URL、本地路径或 bucket 挂载路径），Diffusers 会在 GPU 上通过一次前向传播处理整个列表：

diffusers-cli run \
    --model black-forest-labs/FLUX.1-Kontext-dev --dtype bf16 \
    --pipeline-kwargs '{
        "prompt": ["make it grey", "make it pink", "make it blue"],
        "image": [
            "https://.../cat1.png",
            "https://.../cat2.png",
            "https://.../cat3.png"
        ]
    }'

加载

配置 CLI 如何加载模型权重和自定义流水线代码。

• --dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32} — 权重数据类型。

• --device-map <value> — 组件放置。接受 torch 设备字符串（cuda、cuda:0、cpu、mps）、balanced（自动将组件拆分到可见的 GPU 上），或用于显式指定每个组件放置位置的 JSON 字典。 如果省略，则自动检测。有关更多详细信息，请参阅 device_map。

• --variant fp16 — 选择权重变体。

• --revision <sha> — 固定特定的模型版本。

• --trust-remote-code — 允许使用来自 Hub 的自定义代码（对于包含自定义 pipeline 类或模块化模块的仓库是必需的）。有关标准自定义 pipeline，请参阅 Community pipelines；有关模块化 Diffusers，请参阅 Modular Diffusers。

• --lora <spec> — 在加载后附加一个 LoRA 适配器。每个值都是一个 JSON 字典。重复该标志以堆叠多个适配器。每个条目中 lora_id 为必填项，lora_scale 默认为 1.0，adapter_name 为可选项（堆叠时会自动生成为 lora_<i>）。

  • 单个：--lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'
  • 多个：--lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.6, "adapter_name": "koda"}' --lora '{"lora_id": "Shakker-Labs/FLUX.1-dev-LoRA-AntiBlur", "lora_scale": 0.4}'

  所有规格均由 pipeline.load_lora_weights(...) 加载，然后通过一次 pipeline.set_adapters(names, adapter_weights=scales) 调用同时激活。有关适配器堆叠、缩放调度以及热切换的详细说明，请参阅 LoRA。

优化

• --cpu-offload {model, group, auto} — offload 目标来自 --device-map (offload 所需的纯设备字符串）。
  • model — 用于标准流水线，enable_model_cpu_offload。参见 模型卸载。
  • group — 用于标准流水线，调用 enable_group_offload(offload_type="leaf_level", use_stream=True)。请参阅 组卸载。
  • auto — 仅在 ComponentsManager 中支持模块化。标准模式在模块化管道中会抛出异常。auto 在标准管道中会抛出异常。
• --offload-margin <size> — 在 --cpu-offload auto 下，为激活值保留的设备内存大小，作为 memory_reserve_margin 参数传递给 enable_auto_cpu_offload（默认值为 3GB）。如果大画布在前向传播过程中出现内存不足，请调高此值。由于 offloader 会在组件能够容纳时保持其驻留，因此在高显存显卡上，默认的 margin 可能无法为长视频的激活值留出足够的空间。
• --attention-backend — 托管在 Hub 上的注意力内核，首次使用时会自动下载。可选值为 default 以及 Diffusers 中注册的 Hub 后端（例如 flash_hub、flash_varlen_hub、flash_4_hub、sage_hub、sage_blackwell_hub）。运行 diffusers-cli run --help 可查看当前列表。它仅支持基于 Transformer 的流水线，在旧版 UNet 流水线中会被忽略并给出警告。参见 注意力后端。
• --vae-tiling / --vae-slicing — 降低 VAE 解码的显存占用。参见 VAE 分块 和 VAE 切片。
• --compile [JSON] — 使用 torch.compile 编译 denoiser 模块。对于包含重复块的模块，CLI 优先采用 regional compilation。仅使用 --compile 时，默认使用 fullgraph=true。JSON 对象会直接传递给 torch.compile。不支持与 --context-parallel 一起使用。
• --context-parallel — 基于 DiT 的流水线上的 Ulysses 风格上下文并行。本地需要 torchrun，但在 --remote 下，CLI 会为您封装 torchrun --nproc-per-node=gpu。参见 上下文并行。

模块化流水线

run 会自动检测 模块化仓库——无论是因为它附带了 modular_model_index.json，还是因为其 model_index.json 中指定了 ModularPipeline 的子类——因此无需使用任何标志即可启用。

一些模块化仓库定义了多个 工作流，它们类似于命名任务，共享相同的组件，但运行的模块和接受的输入有所不同。例如，MiniMax-H3 提供了 t2va（文本转视频和音频）、fl2va（首帧和/或尾帧）以及 ref2va（图像、视频和音频参考的有序混合）。传入 --workflow 以选择其中一个：

diffusers-cli run \
    --model MiniMaxAI/MiniMax-H3 --workflow fl2va \
    --pipeline-kwargs '{
        "prompt": "the camera pushes in slowly as rain falls",
        "image": "opening-frame.png",
        "last_image": "closing-frame.png",
        "num_frames": 124
    }' \
    --output-key videos --output-key audio \
    --fps 24 --sampling-rate 32000 \
    --cpu-offload auto --dtype bf16

选择某个工作流后，仅保留该任务对应的模块，因此流水线只声明所需的组件，load_components 也只获取相应的子文件夹。省略 --workflow 参数可保留所有可用工作流，让流水线根据每次调用时传入的输入自行选择。

diffusers-cli --format json schema --model MiniMaxAI/MiniMax-H3 --trust-remote-code

--workflow 仅适用于模块化流水线。在标准流水线中，该参数会被忽略并触发警告。

模块化流水线返回的是 PipelineState，而非单个输出对象，因此 --output-key 用于指定要保存的中间结果。

输出

run 会检测流水线输出类型：

• PIL.Image/list → <NNNN>.png（零填充索引，例如 0000.png）
• 图像序列 → 0000.mp4（--fps 控制帧率，默认值为 8）
• 音频数组 → 0000.wav（--sampling-rate 控制采样率）
• 其他任何内容 → JSON 转储

默认输出目录格式为 ~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/。每次运行都会生成一个独立的子目录，因此连续调用不会相互覆盖。

使用 --output <path> 进行覆盖。路径的展开方式取决于其形式和批处理大小：

目录输出始终使用纯填充名称（0000、0001、……）。显式文件路径会保留您选择的词干，并在批次产生多个输出时附加填充索引。

使用 --push-to 将输出上传到 Hugging Face 存储桶。它接受一个：

• HF 存储桶 ID（<namespace>/<name>）
• hf://buckets/<namespace>/<name>[/<subpath>] HF URI
• 浏览器 URL

子路径用作文件夹前缀。如果存储桶不存在，则会自动创建，对象将放置在 [<subpath>/]<run_id>/<filename> 下。

# HF bucket id — files at hf://buckets/alice/edit-outputs/<run_id>/<file>
--push-to alice/edit-outputs

# URI with subpath — files at hf://buckets/alice/edit-outputs/greyscale/2026-07/<run_id>/<file>
--push-to hf://buckets/alice/edit-outputs/greyscale/2026-07

# Browser URL copy-paste from the Hub also works.
--push-to https://huggingface.co/buckets/alice/edit-outputs/tree/greyscale/2026-07

下表描述了远程运行。对于本地运行，--push-to 会上传本地保存的输出。它不会抑制本地文件的创建。

--format 用于控制标准输出中的元数据（路径、耗时、沙箱信息）。它不会更改媒体文件本身的格式。生成的图像始终为 PNG，视频为 MP4，音频为 WAV。

远程执行（--remote）

在 Hugging Face Sandbox 中运行相同的调用——这是一个由 CLI 通过 HTTP 驱动的隔离云虚拟机：它会上传输入、运行流水线、下载输出，然后终止沙箱。需要 huggingface_hub>=1.23。

沙箱从 diffusers/diffusers-cli-cuda 启动，这是一个预构建的镜像，已内置 torch、CUDA 以及 CLI 的依赖项，因此冷启动时可直接开始生成，而无需先进行安装。

diffusers-cli run \
    --model black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "an astronaut riding a horse"}' \
    --remote --flavor a100-large

远程标志：

• --flavor <name> — 沙箱硬件（例如，a10g-small、h200、rtx-pro-6000）。
• --timeout <duration> — 沙箱内运行命令的最大实际耗时（默认值为 10m）。
• --dependencies <pkg> — 额外的 pip 依赖项（可重复使用），将安装在镜像之上。适用于固定 diffusers 分支的 tarball 或添加特定于流水线的额外依赖项。
• --namespace <name> — 在不同的 HF 组织/账户下创建沙箱。
• --image <ref> — 覆盖沙箱镜像。该镜像必须包含与 --flavor 的驱动程序兼容的 torch + CUDA。随后，CLI 会在每个冷启动的沙箱上安装其自身的依赖项，而默认镜像则避免了这一点。
• --volume <bucket-id>[:<mount-path>] — 将一个 HF 存储桶 以可读写目录的形式挂载到沙箱中（可重复使用）。默认挂载路径为 /mnt/buckets/<bucket-id>。在 --pipeline-kwargs 中引用已挂载的文件时，可将其视为任意其他本地路径。 仅在创建新沙箱时生效，通过 --sandbox-id 重新连接时会被忽略。

默认情况下，每次 --remote 运行都是临时的（创建 → 运行 → 下载 → 终止）。若要在多次运行之间复用已就绪的沙箱——保留其磁盘上的依赖项、模型权重缓存以及 torch.compile 缓存——请保持沙箱存活并重新连接：

• --keep-alive — 运行结束后不终止沙箱。其 id 会被打印出来。
• --sandbox-id <id> — 重新连接到保持活动的沙箱，而不是创建一个新的沙箱。
• --idle-timeout <duration> — 在此时长无活动后自动关闭（默认 10m）。仅在创建新沙箱时生效，通过 --sandbox-id 重新连接时会被忽略。

# First run keeps the sandbox alive and prints sandbox_id=<id>.
diffusers-cli run -m black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "a cat"}' --remote --flavor a100-large --keep-alive

# Reconnect for the next run — the model is already cached, so only inference runs.
diffusers-cli run -m black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "a dog"}' --remote --flavor a100-large --sandbox-id <id>

# Stop it when done (or let it timeout).
hf sandbox kill <id>

custom_blocks

将本地 ModularPipelineBlocks 子类打包以便上传至 Hub。读取 Python 文件，通过 AST 扫描其中继承自 ModularPipelineBlocks 或其某个复合子类（SequentialPipelineBlocks、AutoPipelineBlocks、ConditionalPipelineBlocks、LoopSequentialPipelineBlocks）的类，实例化所选的类，并在当前工作目录中调用 save_pretrained。

# Package the first block found in ./block.py
diffusers-cli custom_blocks

# Point at a different file / pick a specific class
diffusers-cli custom_blocks --block_module_name my_block.py --block_class_name MyDenoiseBlock

块类必须能够以零个构造参数实例化，并在 __init__ 中硬编码默认值，或在调用时从 pipeline 的 state 中读取配置。

fp16_safetensors

此命令现已弃用，并将在未来版本中移除。

将 Hub 上的检查点转换为 fp16 .safetensors 并推送结果。这有助于缩小仓库的权重体积，从而加快加载速度。有关确切参数，请参阅 diffusers-cli fp16_safetensors --help。

技能

从 diffusers 仓库安装技能（.ai/skills/）。

# Install a single skill
diffusers-cli skills add "<skill name>"

# Install every skill in the registry
diffusers-cli skills add --all

# List available skills with a one-line summary of each
diffusers-cli skills list

# Preview a skill's SKILL.md without installing
diffusers-cli skills preview diffusers-cli

# Refetch and reinstall every managed skill
diffusers-cli skills update

# Install to the user-level directory instead of the current project
diffusers-cli skills add diffusers-cli --global

# Install for one agent instead of detecting it from the environment
diffusers-cli skills add --all --claude   # or --codex / --cursor

若未指定目标标志，CLI 将为启动它的 agent 进行安装；若无法确定，则将为所有 agent 安装。Claude Code 会在 .claude/skills/diffusers/ 下安装一个插件包（命名空间为 /diffusers:<skill name>）。Codex 和 Cursor 则会安装到 .agents/skills/<skill name>/。