Interface en ligne de commande

diffusers-cli est un client en ligne de commande pour exécuter, inspecter et empaqueter les pipelines Diffusers.

Commandes disponibles

Cette page ne détaille pas toutes les options de chaque sous-commande. Pour obtenir la liste complète et à jour des options de toute sous-commande, exécutez diffusers-cli <command> --help (diffusers-cli run --help).

env

Affiche les versions de Python, PyTorch et Diffusers, les informations CUDA et les dépendances optionnelles installées. Utilisez-le lors de l’ouverture d’un ticket afin que les mainteneurs puissent reproduire votre configuration.

diffusers-cli env

schema

Retourne les entrées acceptées par le pipeline sans télécharger les poids. Utilisez-le lors de la construction de --pipeline-kwargs pour run.

Seul le fichier d’index est récupéré. Les pipelines standard lisent model_index.json. Les pipelines modulaires lisent modular_model_index.json. Les dépôts à blocs personnalisés lisent modular_config.json et nécessitent --trust-remote-code, car leur chargement exécute du code du 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

Exécutez un pipeline de bout en bout. L’interface en ligne de commande détecte automatiquement les dépôts standard et modulaires. Elle charge automatiquement les entrées multimédias à partir d’URL ou de chemins locaux, enregistre les sorties selon le type de retour du pipeline et peut s’exécuter à distance sur un Hugging Face Sandbox via --remote.

Exemple minimal :

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

Passage des arguments du pipeline

--pipeline-kwargs prend un objet JSON qui est transmis à pipeline(**kwargs). Les valeurs de chaîne aux clés d’entrée média connues sont chargées automatiquement :

• Images (image, last_image, mask_image, control_image, ip_adapter_image, image_2) → PIL.Image via load_image.
• Vidéos (video, control_video) → list[PIL.Image] via load_video.
• Audio (initial_audio_waveforms, reference_audio, src_audio) → torch.Tensor via 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}'

Les clés média et texte acceptent toutes deux un tableau JSON pour traiter un lot via un seul appel de pipeline. Chaque entrée d’une liste média est chargée individuellement (URL, chemin local ou chemin de montage de bucket), et Diffusers traite la liste entière en un seul passage avant sur le 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"
        ]
    }'

Chargement

Configurez la façon dont l’interface en ligne de charge (CLI) charge les poids du modèle et le code de pipeline personnalisé.

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

• --device-map <value> — placement des composants. Accepte une chaîne de device torch (cuda, cuda:0, cpu, mps), balanced (répartit automatiquement les composants entre les GPU visibles) ou un dictionnaire JSON pour un placement explicite par composant. Détecté automatiquement si omis. Voir device_map pour plus de détails.

• --variant fp16 — choisir une variante de poids.

• --revision <sha> — épingler une révision spécifique du modèle.

• --trust-remote-code — autorise le code personnalisé issu du Hub (nécessaire pour les dépôts qui incluent des classes de pipeline personnalisées ou des blocs modulaires). Consultez Community pipelines pour les pipelines personnalisés standard et Modular Diffusers.

• --lora <spec> — attache un adaptateur LoRA après le chargement. Chaque valeur est un dictionnaire JSON. Répétez le drapeau pour empiler plusieurs adaptateurs. lora_id est obligatoire pour chaque entrée, lora_scale est défini par défaut sur 1.0, et adapter_name est facultatif (généré automatiquement sous la forme lora_<i> lors de l’empilement).

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

  Toutes les spécifications sont chargées par pipeline.load_lora_weights(...), puis activées ensemble avec un seul appel à pipeline.set_adapters(names, adapter_weights=scales). Consultez LoRA pour un guide détaillé sur le superposition d'adaptateurs, la planification des échelles et le changement à chaud.

Optimisations

• --cpu-offload {model, group, auto} — la cible de déchargement provient de --device-map (chaîne d'appareil simple requise pour le déchargement). model — enable_model_cpu_offload pour les pipelines standard. Voir Déchargement du modèle. group — enable_group_offload(offload_type="leaf_level", use_stream=True) pour les pipelines standard. Voir Déchargement par groupe. auto — uniquement pour les pipelines modulaires avec ComponentsManager. Les modes standard lèvent une erreur sur les pipelines modulaires. auto lève une erreur sur les pipelines standard.
  • model — enable_model_cpu_offload pour les pipelines standard. Voir Déchargement du modèle.
  • group — enable_group_offload(offload_type="leaf_level", use_stream=True) pour les pipelines standard. Voir Group offloading.
  • auto — uniquement en mode modulaire avec ComponentsManager. Les modes standard lèvent une exception sur les pipelines modulaires. auto lève une exception sur les pipelines standard.
• --offload-margin <size> — mémoire de l’appareil laissée libre pour les activations sous --cpu-offload auto, transmise à enable_auto_cpu_offload en tant que memory_reserve_margin (valeur par défaut 3GB). Augmentez cette valeur si une grande toile épuise la mémoire en cours de propagation avant. Le déchargeur conserve les composants en mémoire tant qu’ils y tiennent, de sorte qu’avec une carte à forte VRAM, la marge par défaut peut laisser trop peu de place pour les activations d’une longue vidéo.
• --attention-backend — Noyaux d’attention hébergés sur le Hub, téléchargés automatiquement lors de la première utilisation. Les choix sont default ainsi que les backends du Hub enregistrés dans Diffusers (par exemple flash_hub, flash_varlen_hub, flash_4_hub, sage_hub, sage_blackwell_hub). Exécutez diffusers-cli run --help pour obtenir la liste actuelle. Il ne prend en charge que les pipelines basés sur des Transformers et est ignoré avec un avertissement sur les pipelines UNet legacy. Voir Backends d’attention.
• --vae-tiling / --vae-slicing — réduit la VRAM utilisée par le décodage VAE. Consultez tiling VAE et slicing VAE.
• --compile [JSON] — compile les modules du débruiteur avec torch.compile. L’interface en ligne de commande privilégie la compilation régionale pour les modules comportant des blocs répétés. L’option --compile seule utilise fullgraph=true. Un objet JSON est transmis à torch.compile. Non pris en charge avec --context-parallel.
• --context-parallel — parallélisme de contexte de type Ulysses sur un pipeline basé sur DiT. Nécessite localement torchrun, mais sous --remote, l’interface en ligne de commande encapsule torchrun --nproc-per-node=gpu pour vous. Voir Parallélisme de contexte.

Pipelines modulaires

run détecte automatiquement un dépôt modulaire — soit parce qu’il contient un modular_model_index.json, soit parce que son model_index.json référence une sous-classe de ModularPipeline — aucun drapeau n’est donc nécessaire pour l’activer.

Certains dépôts modulaires définissent plusieurs workflows semblables à des tâches nommées qui partagent des composants mais diffèrent par les blocs exécutés et les entrées qu’ils acceptent. MiniMax-H3, par exemple, propose t2va (texte vers vidéo et audio), fl2va (image clé première et/ou dernière) et ref2va (un mélange ordonné de références image, vidéo et audio). Passez --workflow pour en sélectionner un :

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

Sélectionner un workflow ne conserve que les blocs de cette tâche, de sorte que le pipeline ne déclare que les composants dont il a besoin et load_components ne récupère que leurs sous-dossiers. Omettez --workflow pour conserver tous les workflows disponibles et laisser le pipeline choisir à chaque appel en fonction des entrées qui lui sont fournies.

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

--workflow s'applique uniquement aux pipelines modulaires. Il est ignoré avec un avertissement sur les pipelines standard.

Un pipeline modulaire renvoie un PipelineState plutôt qu'un seul objet de sortie, de sorte que --output-key désigne l'intermédiaire à enregistrer.

Sorties

run détecte le type de sortie du pipeline :

• PIL.Image/liste → <NNNN>.png (index à zéros, par ex. 0000.png)
• Séquence d'images → 0000.mp4 (--fps contrôle la fréquence d'images, valeur par défaut 8)
• Tableau audio → 0000.wav (--sampling-rate contrôle le taux)
• Tout le reste → déchargement JSON

Le format du répertoire de sortie par défaut est ~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/. Chaque exécution reçoit son propre sous-répertoire afin que les invocations successives ne s'écrasent pas.

Utilisez --output <path> pour l'écraser. La manière dont le chemin est développé dépend de sa forme et de la taille du lot :

Les sorties de répertoire utilisent toujours des noms nus avec zéros d’alignement (0000, 0001, …). Les chemins de fichiers explicites conservent le préfixe choisi et reçoivent l’index aligné en suffixe lorsque le lot produit plusieurs sorties.

Utilisez --push-to pour téléverser les résultats dans un seau de stockage Hugging Face. Il accepte un :

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

Un sous-chemin est utilisé comme préfixe de dossier. Le bucket est créé s'il est manquant, et les objets sont placés sous [<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

Le tableau ci-dessous décrit les exécutions distantes. Pour les exécutions locales, --push-to téléverse la sortie enregistrée localement. Il ne supprime pas la création de fichiers locaux.

--format forme les métadonnées de la sortie standard (chemins, chronométrage, informations sur le bac à sable). Il ne modifie pas le format des fichiers des médias eux-mêmes. Les images écrites sont toujours au format PNG, les vidéos en MP4 et l’audio en WAV.

Exécution à distance ( --remote )

Effectuez le même appel dans un Hugging Face Sandbox — une VM cloud isolée que le CLI pilote via HTTP : il téléverse les entrées, exécute le pipeline, télécharge les sorties, puis met fin au sandbox. Nécessite huggingface_hub>=1.23.

Le bac à sable démarre à partir de diffusers/diffusers-cli-cuda, une image préconstruite qui inclut déjà torch, CUDA et les dépendances du CLI, de sorte qu’une exécution à froid commence à générer au lieu d’installer d’abord.

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

Drapeaux distants :

• --flavor <name> — matériel de la sandbox (par exemple, a10g-small, h200, rtx-pro-6000).
• --timeout <duration> — durée maximale réelle pour la commande d’exécution dans le bac à sable (par défaut 10m).
• --dependencies <pkg> — dépendances pip supplémentaires (répétable), installées par-dessus l’image. Utile pour épingler un tarball de branche de diffusers ou ajouter des extras spécifiques à un pipeline.
• --namespace <name> — crée le bac à sable sous une autre organisation/compte HF.
• --image <ref> — remplace l’image du bac à sable. Elle doit inclure torch + CUDA compatible avec le pilote de votre --flavor. L’interface en ligne de commande installe alors ses propres dépendances par-dessus dans chaque bac à sable froid, ce que l’image par défaut évite.
• --volume <bucket-id>[:<mount-path>] — monte un bucket de stockage HF dans le bac à sable en tant que répertoire en lecture-écriture (répétable). Le chemin de montage par défaut est /mnt/buckets/<bucket-id>. Référencez les fichiers montés depuis --pipeline-kwargs comme n’importe quel autre chemin local. Appliqué uniquement lors de la création d’un nouveau bac à sable et ignoré lors de la reconnexion via --sandbox-id.

Par défaut, chaque exécution --remote est éphémère (création → exécution → téléchargement → arrêt). Pour réutiliser un bac à sable chaud entre les exécutions — en conservant les dépendances, le cache des poids du modèle et le cache torch.compile sur son disque —, maintenez-le en vie et reconnectez-vous :

• --keep-alive — ne pas mettre fin au bac à sable après l’exécution. Son identifiant est affiché.
• --sandbox-id <id> — se reconnecter à un sandbox maintenu actif au lieu d’en créer un nouveau.
• --idle-timeout <duration> — arrêt automatique après cette durée d’inactivité (par défaut 10m). Appliqué uniquement lors de la création d’une nouvelle sandbox et ignoré lors d’une reconnexion 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

Emballer une sous-classe locale de ModularPipelineBlocks pour son téléversement sur le Hub. Lit un fichier Python, l’analyse via AST pour détecter les classes dérivant de ModularPipelineBlocks ou de l’une de ses sous-classes composites (SequentialPipelineBlocks, AutoPipelineBlocks, ConditionalPipelineBlocks, LoopSequentialPipelineBlocks), instancie celle choisie et appelle save_pretrained dans le répertoire de travail courant.

# 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

The block class must be instantiable with zero constructor args and hardcodes defaults in __init__ or read config from the pipeline state at call time.

fp16_safetensors

Cette commande est désormais obsolète et sera supprimée dans une version future.

Convertir un point de contrôle sur le Hub en .safetensors fp16 et pousser le résultat. Utile pour réduire la taille des poids d’un dépôt afin d’accélérer le chargement. Consultez diffusers-cli fp16_safetensors --help pour les arguments exacts.

compétences

Installer les compétences depuis le dépôt 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

Sans drapeau cible, le CLI installe pour l’agent qui l’a lancé, ou pour tous les agents s’il ne peut pas le déterminer. Claude Code reçoit un bundle de plugins sous .claude/skills/diffusers/ (namespacé en tant que /diffusers:<skill name>). Codex et Cursor reçoivent .agents/skills/<skill name>/.