コマンドラインインターフェース

diffusers-cli は、Diffusers のパイプラインを実行、検査、パッケージングするためのコマンドラインクライアントです。

利用可能なコマンド

このページでは、各サブコマンドのすべてのオプションの詳細を記載していません。任意のサブコマンドの最新かつ完全なオプション一覧を確認するには、diffusers-cli <command> --help（diffusers-cli run --help）を実行してください。

env

Python、PyTorch、Diffusers のバージョン、CUDA の情報、およびインストールされている任意の依存関係を出力します。Issue を投稿する際に使用し、メンテナーがあなたの環境を再現できるようにしてください。

diffusers-cli env

スキーマ

重みをダウンロードせずに、パイプラインが受け入れる入力値を返します。run 用の --pipeline-kwargs を構築する際に使用します。

インデックスファイルのみが取得されます。標準のパイプラインはmodel_index.jsonを読み込みます。モジュラーパイプラインはmodular_model_index.jsonを読み込みます。カスタムブロックのリポジトリはmodular_config.jsonを読み込み、Hub上のコードが実行されるため、--trust-remote-codeが必要です。

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

run

パイプラインをエンドツーエンドで実行します。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-kwargs は、pipeline(**kwargs) に転送される JSON オブジェクトを受け取ります。既知のメディア入力キーにある文字列値は自動的に読み込まれます:

• 画像（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配列を受け取り、単一のパイプライン呼び出しでバッチ処理を実行できます。メディアリストの各エントリは個別に読み込まれます（URL、ローカルパス、またはバケットマウントパス）。DiffusersはGPU上で1回のフォワードパスでリスト全体を処理します。

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} — 重みの dtype。

• --device-map <value> — コンポーネントの配置。torch のデバイス文字列（cuda、cuda:0、cpu、mps）、balanced（表示可能な GPU にコンポーネントを自動分割して配置）、またはコンポーネントごとの明示的な配置を指定する JSON 辞書を受け取ります。省略した場合、自動検出されます。詳細は device_map を参照してください。

• --variant fp16 — 重みのバリアントを選択します。

• --revision <sha> — 特定のモデルのリビジョンを固定します。

• --trust-remote-code — Hub からのカスタムコードを許可します(カスタムパイプラインクラスやモジュラーブロックを同梱するリポジトリには必要です)。標準的なカスタムパイプラインについては コミュニティパイプライン、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} — オフロード先は --device-map (オフロードにはプレーンなデバイス文字列が必要です）。
  • 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 の下でアクティベーション用に確保しておくデバイスメモリ量。enable_auto_cpu_offload に memory_reserve_margin として渡されます（デフォルトは 3GB）。大きなキャンバスでフォワードの途中でメモリ不足が発生する場合は、この値を上げてください。オフローダーはコンポーネントが収まる限りレジデントに保つため、VRAM の大きいカードでは、デフォルトのマージンでは長い動画のアクティベーションに十分な領域を確保できない場合があります。
• --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 デコード時の VRAM 使用量を削減します。VAE tiling と VAE slicing を参照してください。
• --compile [JSON] — torch.compileでデノイザーモジュールをコンパイルします。CLIは、繰り返しブロックを持つモジュールに対して地域的コンパイルを優先します。単に--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 は、stdout に出力されるメタデータ（パス、タイミング、サンドボックス情報）の形式を指定します。メディアファイル自体の形式は変更されません。書き出される画像は常に PNG、動画は MP4、音声は WAV です。

リモート実行（--remote）

Hugging Face Sandbox内で同じ呼び出しを実行します。これはCLIがHTTP経由で操作する隔離されたクラウドVMであり、入力をアップロードしてパイプラインを実行し、出力をダウンロードした後にサンドボックスを終了します。huggingface_hub>=1.23が必要です。

サンドボックスは、torch、CUDA、および CLI の依存関係がすでに同梱された事前構築済みイメージである diffusers/diffusers-cli-cuda から起動します。そのため、コールドランではインストールの手順を経ずに、そのまま生成を開始できます。

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 storage bucketをサンドボックスに読み書き可能なディレクトリとしてマウントします（繰り返し指定可能）。デフォルトのマウントパスは/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__内でハードコードするか、呼び出し時にパイプラインのstateから設定を読み取ります。

fp16_safetensors

このコマンドは非推奨となり、将来のバージョンで削除されます。

Hub上のチェックポイントを.safetensors形式のfp16に変換し、結果をプッシュします。リポジトリの重みのサイズを縮小して読み込みを高速化するために有用です。正確な引数については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は起動元のエージェントに対して、または特定できない場合はすべてのエージェントに対してインストールを行います。Claude Codeには.claude/skills/diffusers/の下にプラグインバンドルが配置され（/diffusers:<skill name>として名前空間化されます）、CodexとCursorには.agents/skills/<skill name>/が配置されます。