Antarmuka baris perintah

diffusers-cli adalah klien baris perintah untuk menjalankan, memeriksa, dan mengemas pipeline Diffusers.

Perintah yang tersedia

Halaman ini tidak memberikan detail untuk semua opsi di bawah setiap subcommand. Untuk daftar lengkap dan selalu terkini dari opsi untuk subcommand apa pun, jalankan diffusers-cli <command> --help (diffusers-cli run --help).

env

Menampilkan versi Python, PyTorch, Diffusers, info CUDA, dan dependensi opsional yang terpasang. Gunakan ini saat membuka issue agar maintainer dapat mereproduksi setup Anda.

diffusers-cli env

schema

Mengembalikan input yang diterima pipeline tanpa mengunduh bobot. Gunakan ini saat membangun --pipeline-kwargs untuk run.

Hanya file indeks yang diambil. Pipeline standar membaca model_index.json. Pipeline modular membaca modular_model_index.json. Repo dengan blok kustom membaca modular_config.json dan membutuhkan --trust-remote-code, karena memuatnya akan menjalankan kode 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

run

Jalankan pipeline secara end-to-end. CLI mendeteksi secara otomatis apakah repo bersifat standar atau modular. CLI memuat input media secara otomatis dari URL atau path lokal, menyimpan output berdasarkan tipe return dari pipeline, dan dapat dijalankan secara remote di Hugging Face Sandbox melalui --remote.

Contoh minimal:

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

Menyalurkan argumen pipeline

--pipeline-kwargs menerima objek JSON yang diteruskan ke pipeline(**kwargs). Nilai string pada kunci input media yang dikenal akan dimuat secara otomatis:

• Gambar (image, last_image, mask_image, control_image, ip_adapter_image, image_2) → PIL.Image melalui load_image.
• Video (video, control_video) → list[PIL.Image] melalui load_video.
• Audio (initial_audio_waveforms, reference_audio, src_audio) → torch.Tensor melalui torchaudio.load.

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}'

Kunci media dan kunci teks sama-sama menerima array JSON untuk menjalankan batch melalui satu panggilan pipeline. Setiap entri dalam daftar media dimuat secara individual (URL, jalur lokal, atau jalur bucket-mount), dan Diffusers memproses seluruh daftar dalam satu forward pass di 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"
        ]
    }'

Memuat

Konfigurasikan cara CLI memuat bobot model dan kode pipeline kustom.

• --dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32} — dtype bobot.

• --device-map <value> — penempatan komponen. Menerima string perangkat torch (cuda, cuda:0, cpu, mps), balanced (membagi komponen secara otomatis di antara GPU yang terlihat), atau dict JSON untuk penempatan per komponen secara eksplisit. Dideteksi secara otomatis jika diabaikan. Lihat device_map untuk detail lebih lanjut.

• --variant fp16 — pilih varian bobot.

• --revision <sha> — mengunci revisi model tertentu.

• --trust-remote-code — mengizinkan kode kustom dari Hub (diperlukan untuk repositori yang menyertakan kelas pipeline kustom atau blok modular). Lihat Community pipelines untuk pipeline kustom standar dan Modular Diffusers.

• --lora <spec> — lampirkan adapter LoRA setelah pemuatan. Setiap nilai adalah dict JSON. Ulangi flag untuk menumpuk beberapa adapter. lora_id wajib untuk setiap entri, lora_scale secara default bernilai 1.0, dan adapter_name bersifat opsional (dibuat otomatis sebagai lora_<i> saat menumpuk).

  • Tunggal: --lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'
  • Berlebih: --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}'

  Semua spesifikasi dimuat oleh pipeline.load_lora_weights(...), kemudian diaktifkan bersama dengan satu panggilan pipeline.set_adapters(names, adapter_weights=scales). Lihat LoRA untuk penjelasan lebih mendalam tentang penumpukan adapter, penjadwalan skala, dan penggantian cepat.

Optimasi

• --cpu-offload {model, group, auto} — target onload berasal dari --device-map (string perangkat polos yang diperlukan untuk offload). model — enable_model_cpu_offload untuk pipeline standar. Lihat Model offloading. group — enable_group_offload(offload_type="leaf_level", use_stream=True) untuk pipeline standar. Lihat Group offloading. auto — hanya modular dengan ComponentsManager. Mode standar memicu error pada pipeline modular. auto memicu error pada pipeline standar.
  • model — enable_model_cpu_offload for standard pipelines. See Model offloading.
  • group — enable_group_offload(offload_type="leaf_level", use_stream=True) untuk pipeline standar. Lihat Group offloading.
  • auto — hanya modular dengan ComponentsManager. Mode standar memicu error pada pipeline modular. auto memicu error pada pipeline standar.
• --offload-margin <size> — memori perangkat yang dipertahankan bebas untuk aktivasi di bawah --cpu-offload auto, diteruskan ke enable_auto_cpu_offload sebagai memory_reserve_margin (default 3GB). Naikkan nilai ini ketika kanvas besar kehabisan memori di tengah forward. Offloader mempertahankan komponen tetap resident selama masih muat, sehingga pada kartu dengan VRAM tinggi, margin default dapat menyisakan ruang yang terlalu sedikit untuk aktivasi video panjang.
• --attention-backend — Kernel attention yang di-host di Hub, diunduh secara otomatis saat pertama kali digunakan. Pilihan meliputi default ditambah backend Hub yang terdaftar di Diffusers (misalnya flash_hub, flash_varlen_hub, flash_4_hub, sage_hub, sage_blackwell_hub). Jalankan diffusers-cli run --help untuk melihat daftar terkini. Opsi ini hanya mendukung pipeline berbasis Transformer, dan akan diabaikan dengan peringatan pada pipeline UNet lama. Lihat Backend attention.
• --vae-tiling / --vae-slicing — menurunkan VRAM decode VAE. Lihat VAE tiling dan VAE slicing.
• --compile [JSON] — mengompilasi modul denoiser dengan torch.compile. CLI lebih memilih regional compilation untuk modul dengan blok yang berulang. --compile polos menggunakan fullgraph=true. Objek JSON diteruskan ke torch.compile. Tidak didukung dengan --context-parallel.
• --context-parallel — paralelisme konteks bergaya Ulysses pada pipeline berbasis DiT. Secara lokal memerlukan torchrun, tetapi di bawah --remote, CLI membungkus torchrun --nproc-per-node=gpu untuk Anda. Lihat Paralelisme konteks.

Pipeline modular

run mendeteksi repo modular secara otomatis — baik karena menyertakan modular_model_index.json, maupun karena model_index.json-nya menyebut subclass ModularPipeline — sehingga tidak perlu flag untuk mengaktifkannya.

Beberapa repositori modular mendefinisikan beberapa workflows seperti tugas bernama yang berbagi komponen tetapi berbeda dalam blok mana yang dijalankan dan input apa yang diambil. MiniMax-H3, misalnya, menawarkan t2va (teks ke video dan audio), fl2va (keyframe pertama dan/atau terakhir) dan ref2va (campuran terurut dari referensi gambar, video, dan audio). Lewatkan --workflow untuk memilih salah satu:

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

Memilih satu workflow hanya mempertahankan blok untuk tugas tersebut, sehingga pipeline hanya mendeklarasikan komponen yang dibutuhkan dan load_components hanya mengambil subfolder-nya. Lewatkan --workflow untuk mempertahankan semua workflow yang tersedia dan membiarkan pipeline memilih per pemanggilan berdasarkan input yang diberikan.

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

--workflow hanya berlaku untuk pipeline modular. Opsi ini diabaikan dengan peringatan pada pipeline standar.

Pipeline modular mengembalikan PipelineState alih-alih satu objek output, sehingga --output-key menamai intermediate yang akan disimpan.

Output

run mendeteksi tipe output pipeline:

• PIL.Image/list → <NNNN>.png (indeks dengan nol di depan, mis. 0000.png)
• Urutan gambar → 0000.mp4 (--fps mengontrol framerate, default 8)
• Array audio → 0000.wav (--sampling-rate mengontrol laju)
• Hal lain → dump JSON

Format direktori output default adalah ~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/. Setiap run memiliki subdirektori sendiri sehingga pemanggilan berurutan tidak saling menimpa.

Override dengan --output <path>. Cara path diperluas bergantung pada bentuknya dan ukuran batch:

Output direktori selalu menggunakan nama bantalan polos (0000, 0001, …). Jalur file eksplisit mempertahankan stem yang Anda pilih dan mendapatkan indeks bantalan yang ditambahkan ketika batch menghasilkan beberapa output.

Gunakan --push-to untuk mengunggah output ke bucket penyimpanan Hugging Face. Parameter ini menerima:

• ID bucket HF (<namespace>/<name>)
• hf://buckets/<namespace>/<name>[/<subpath>] URI HF
• URL browser

Subpath digunakan sebagai prefiks folder. Bucket dibuat jika belum ada, dan objek ditempatkan di bawah [<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

Tabel di bawah ini menjelaskan eksekusi jarak jauh. Untuk eksekusi lokal, --push-to mengunggah output yang disimpan secara lokal. Hal ini tidak menekan pembuatan file lokal.

--format membentuk metadata stdout (path, timing, info sandbox). Parameter ini tidak mengubah format file dari media itu sendiri. Gambar yang ditulis selalu PNG, video MP4, dan audio WAV.

Eksekusi jarak jauh ( --remote )

Jalankan pemanggilan yang sama di dalam Hugging Face Sandbox — VM cloud terisolasi yang dikendalikan CLI melalui HTTP: mengunggah input, menjalankan pipeline, mengunduh output, lalu mengakhiri sandbox. Memerlukan huggingface_hub>=1.23.

Sandbox berjalan dari diffusers/diffusers-cli-cuda, sebuah image prebuilt yang sudah menyertakan torch, CUDA, dan dependensi CLI, sehingga eksekusi dingin langsung mulai menghasilkan output tanpa perlu menginstal terlebih dahulu.

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

Flag jarak jauh:

• --flavor <name> — perangkat keras sandbox (misalnya, a10g-small, h200, rtx-pro-6000).
• --timeout <duration> — batas waktu maksimum untuk perintah run di dalam sandbox (default 10m).
• --dependencies <pkg> — dependensi pip tambahan (dapat diulang), diinstal di atas image. Berguna untuk mengunci tarball cabang diffusers atau menambahkan ekstra yang spesifik untuk pipeline.
• --namespace <name> — buat sandbox di bawah org/akun HF yang berbeda.
• --image <ref> — menimpa image sandbox. Harus menyertakan torch + CUDA yang kompatibel dengan driver --flavor Anda. CLI kemudian menginstal dependensinya sendiri di atasnya di setiap sandbox dingin, yang dihindari oleh image default.
• --volume <bucket-id>[:<mount-path>] — mount bucket penyimpanan HF ke dalam sandbox sebagai direktori baca-tulis (dapat diulang). Path mount default adalah /mnt/buckets/<bucket-id>. Rujuk file yang di-mount dari --pipeline-kwargs seperti path lokal lainnya. Hanya diterapkan saat pembuatan sandbox baru dan diabaikan saat menyambung ulang melalui --sandbox-id.

Secara default, setiap eksekusi --remote bersifat sementara (buat → jalankan → unduh → matikan). Untuk menggunakan ulang sandbox yang sudah aktif antar eksekusi — dengan mempertahankan dependensi, cache bobot model, dan cache torch.compile di disk-nya — biarkan tetap hidup dan sambungkan kembali:

• --keep-alive — jangan akhiri sandbox setelah eksekusi. ID-nya akan dicetak.
• --sandbox-id <id> — sambungkan ulang ke sandbox yang dijaga tetap aktif, bukan membuat yang baru.
• --idle-timeout <duration> — auto-shutdown setelah durasi inaktivitas ini (default 10m). Diterapkan hanya saat pembuatan sandbox baru dan diabaikan saat reconnecting via --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

Kemas subclass ModularPipelineBlocks lokal untuk diunggah ke Hub. Membaca file Python, memindai AST-nya untuk kelas yang diturunkan dari ModularPipelineBlocks atau salah satu subclass kompositnya (SequentialPipelineBlocks, AutoPipelineBlocks, ConditionalPipelineBlocks, LoopSequentialPipelineBlocks), menginstansiasi yang dipilih, dan memanggil save_pretrained di direktori kerja saat ini.

# 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

Kelas blok harus dapat diinstansiasi dengan nol argumen konstruktor dan menghardcode nilai default di __init__ atau membaca konfigurasi dari state pipeline pada saat pemanggilan.

fp16_safetensors

Perintah ini sekarang tidak didukung lagi dan akan dihapus dalam versi mendatang.

Konversi checkpoint di Hub menjadi .safetensors fp16 dan dorong hasilnya. Berguna untuk memperkecil ukuran bobot repo agar pemuatan lebih cepat. Lihat diffusers-cli fp16_safetensors --help untuk argumen yang tepat.

keterampilan

Install keterampilan dari repo 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

Tanpa flag target, CLI menginstal untuk agen yang meluncurkannya, atau untuk semua agen jika tidak dapat membedakannya. Claude Code mendapatkan bundle plugin di bawah .claude/skills/diffusers/ (diberi namespace sebagai /diffusers:<skill name>). Codex dan Cursor mendapatkan .agents/skills/<skill name>/.