Diffusers (🧨 Hugging Face Diffusers)
Diffusers est la bibliothèque Python open source de Hugging Face qui fournit des pipelines prêts à l’emploi et des composants modulaires pour l’inférence et l’entraînement de modèles de diffusion (image, vidéo, audio, 3D), supportant Stable Diffusion, SDXL, FLUX, Wan, et des dizaines d’autres architectures.
- Type
- Bibliothèque Python pour modèles de diffusion
- Développeur
- Hugging Face
- Licence
- Open source (Apache 2.0)
- Version actuelle
- v0.37.0 (mars 2026)
- Frameworks
- PyTorch (principal), JAX/Flax
- Python requis
- ≥ 3.10
- Modèles supportés
- SD 1.x/2.x, SDXL, SD 3.x, FLUX, Wan, Cosmos, Kandinsky, DeepFloyd IF, et plus
- Tâches
- Image, vidéo, audio, 3D (inférence + entraînement)
- PyPI
pip install diffusers- GitHub
- github.com/huggingface/diffusers
Qu’est-ce que Diffusers ?
Diffusers est la couche logicielle qui se trouve entre les poids des modèles de diffusion et les interfaces utilisateur. Quand vous utilisez AUTOMATIC1111, ComfyUI, InvokeAI ou n’importe quel outil de génération d’images par IA, il y a de fortes chances qu’un ou plusieurs composants Diffusers soient à l’œuvre en arrière-plan. La bibliothèque fournit les briques de base : les pipelines de génération, les schedulers (algorithmes de débruitage), les modèles (U-Net, Transformers, VAE), et les utilitaires d’entraînement.
Lancée en 2022 par l’équipe Hugging Face, Diffusers suit trois principes de conception : utilisabilité plutôt que performance (le code doit être lisible et facile à utiliser), simple plutôt que facile (les abstractions ne masquent pas la complexité, elles la structurent), et personnalisation plutôt qu’abstraction (chaque composant est accessible et modifiable individuellement).
En pratique, cela signifie que vous pouvez générer une image en 5 lignes de code avec un pipeline prêt à l’emploi, ou décomposer le pipeline en ses composants individuels pour modifier chaque étape du processus de diffusion. C’est cette flexibilité qui fait de Diffusers le choix universel pour les développeurs, chercheurs et intégrateurs.
Concepts clés
Pipelines
Un pipeline Diffusers regroupe tous les composants nécessaires à une tâche de génération (modèle, scheduler, text encoder, VAE) dans une seule classe appelable. La classe de base DiffusionPipeline détecte automatiquement le type de modèle et charge les bons composants.
Les AutoPipelines simplifient encore l’expérience : AutoPipelineForText2Image, AutoPipelineForImage2Image et AutoPipelineForInpainting détectent automatiquement le modèle chargé (SD 1.5, SDXL, Kandinsky, FLUX…) et instancient le pipeline approprié. Vous n’avez pas besoin de savoir quel pipeline spécifique utiliser pour chaque modèle.
from diffusers import AutoPipelineForText2Image
import torch
# Charge automatiquement le bon pipeline pour SDXL
pipe = AutoPipelineForText2Image.from_pretrained(
"stabilityai/stable-diffusion-xl-base-1.0",
torch_dtype=torch.float16
).to("cuda")
image = pipe("a castle on a cliff at sunset").images[0]
image.save("castle.png")Plus de 100 pipelines sont disponibles, couvrant des tâches allant du text-to-image classique à la génération vidéo (Wan, Cosmos), en passant par l’inpainting, l’image-to-image, le ControlNet, IP-Adapter, la super-résolution, la génération audio (AudioLDM), et même la génération de structures moléculaires 3D.
Schedulers (Samplers)
Les schedulers définissent l’algorithme de débruitage utilisé pendant la génération. Diffusers propose plus de 30 schedulers interchangeables : DDIM, DDPM, DPM++ (2M, SDE, multistep), Euler, Euler Ancestral, LMS, UniPC, LCM, et bien d’autres. Chaque scheduler a ses caractéristiques (vitesse de convergence, déterminisme, qualité de détails) et peut être échangé en une ligne de code :
from diffusers import DPMSolverMultistepScheduler
# Remplacer le scheduler par DPM++ 2M
pipe.scheduler = DPMSolverMultistepScheduler.from_config(
pipe.scheduler.config
)Cette interchangeabilité est l’un des grands avantages de Diffusers par rapport aux backends monolithiques : vous pouvez tester instantanément l’effet de différents schedulers sur la même image.
Modèles (composants individuels)
Diffusers fournit les classes de modèles individuels qui composent un pipeline : UNet2DConditionModel (le U-Net standard), Transformer2DModel (pour les architectures DiT comme FLUX et SD 3), AutoencoderKL (le VAE), et les text encoders (via la bibliothèque Transformers de Hugging Face). Chaque composant peut être chargé, inspecté et modifié indépendamment.
Cette modularité permet aux chercheurs de remplacer n’importe quel composant par une version personnalisée (un U-Net modifié, un VAE fine-tuné, un scheduler expérimental) sans réécrire le reste du pipeline.
Intégration Hugging Face Hub
Tous les composants Diffusers sont natifs du Hugging Face Hub. Plus de 10 000 modèles compatibles Diffusers sont hébergés sur le Hub, chargeables en une ligne avec from_pretrained(). Vous pouvez aussi publier vos propres modèles avec push_to_hub(). Le format Diffusers est devenu le standard de facto pour la distribution de modèles de diffusion, aux côtés du format safetensors.
Modèles et architectures supportés
| Architecture | Modèles | Tâche |
|---|---|---|
| Stable Diffusion | SD 1.x, SD 2.x | Image (txt2img, img2img, inpainting) |
| SDXL | SDXL Base, SDXL Refiner, SDXL Turbo | Image (haute résolution) |
| SD 3.x | SD 3, SD 3.5 (Medium, Large, Turbo) | Image (architecture MMDiT) |
| FLUX | FLUX.1 (Dev, Schnell), FLUX.2 Klein | Image (architecture DiT) |
| Wan | Wan 2.1 (T2V, I2V, V2V) | Vidéo (text-to-video, image-to-video) |
| Cosmos | Cosmos Predict2 | Vidéo, simulation physique |
| Kandinsky | Kandinsky 2.2, 3.0 | Image |
| DeepFloyd IF | IF-I, IF-II | Image (pixel-space diffusion) |
| AudioLDM | AudioLDM, AudioLDM 2 | Audio (text-to-audio) |
| Qwen Image | Qwen Image | Image |
| Z-Image | Z-Image, Z-Image Turbo | Image |
Cette liste s’allonge à chaque release. La v0.33 (décembre 2025) a ajouté Wan 2.1. La v0.37 (mars 2026) a introduit le support de Cosmos Predict2 et Qwen Image. La politique de Diffusers est d’ajouter le support des nouveaux modèles dans les jours ou semaines suivant leur publication.
Entraînement et fine-tuning
Diffusers n’est pas seulement une bibliothèque d’inférence. Elle fournit des scripts d’entraînement complets pour les tâches les plus courantes :
DreamBooth
Le script train_dreambooth.py permet de fine-tuner un modèle de diffusion complet avec 3-5 images d’un sujet. Le script train_dreambooth_lora.py applique la technique LoRA au processus DreamBooth pour réduire la VRAM nécessaire. Les deux scripts supportent SD 1.5, SDXL et FLUX.
Textual Inversion
Le script textual_inversion.py optimise un vecteur d’embedding pour associer un concept visuel à un pseudo-mot, sans modifier le modèle. Compatible avec tous les modèles basés sur CLIP.
LoRA
Le script train_text_to_image_lora.py entraîne un adaptateur LoRA sur un dataset personnalisé. C’est la méthode la plus populaire pour personnaliser les modèles de diffusion grâce à son ratio qualité/coût optimal.
ControlNet
Le script train_controlnet.py entraîne un modèle ControlNet personnalisé pour ajouter un nouveau type de conditionnement structurel (contours, profondeur, pose, segmentation) à un modèle de diffusion existant.
Tous ces scripts utilisent la bibliothèque accelerate de Hugging Face pour le multi-GPU, le mixed precision, et l’intégration avec des trackers d’expériences (TensorBoard, Weights & Biases).
Optimisations mémoire
Diffusers intègre de nombreuses optimisations pour réduire la consommation de VRAM, essentielles pour les GPU grand public :
| Optimisation | Effet | Activation |
|---|---|---|
| Attention slicing | Réduit la VRAM en calculant l’attention par tranches | pipe.enable_attention_slicing() |
| xFormers | Attention mémoire-efficiente (NVIDIA GPU) | pipe.enable_xformers_memory_efficient_attention() |
| CPU offloading | Déplace les modèles sur CPU entre les étapes | pipe.enable_model_cpu_offload() |
| Sequential CPU offloading | Décharge chaque couche individuellement (plus lent, VRAM minimale) | pipe.enable_sequential_cpu_offload() |
| VAE slicing | Décode le VAE par tranches pour les grands batchs | pipe.enable_vae_slicing() |
| VAE tiling | Décode le VAE par tuiles pour les grandes résolutions | pipe.enable_vae_tiling() |
| Half precision (FP16) | Réduit la VRAM de moitié | torch_dtype=torch.float16 |
| Quantization (BnB, GGUF) | Compresse les poids du modèle (4-bit, 8-bit) | Via BitsAndBytes, GGUF, TorchAO |
Le enable_model_cpu_offload() est la méthode la plus recommandée pour les GPU à VRAM limitée : elle déplace automatiquement les composants entre GPU et CPU selon les besoins, en gardant en VRAM uniquement le composant actif. Le surcoût en temps est minimal (quelques secondes par génération).
Depuis la v0.36, Diffusers supporte nativement la quantization via BitsAndBytes, GGUF, optimum-quanto, TorchAO et nvidia-modelopt, ce qui réduit considérablement la VRAM requise pour les modèles volumineux comme FLUX et Z-Image.
Installation et utilisation rapide
Installation
# Installation de base
pip install diffusers transformers accelerate torch
# Avec support quantization (optionnel)
pip install bitsandbytes # pour NF4/INT8
# Avec xFormers (GPU NVIDIA, optionnel mais recommandé)
pip install xformersDiffusers requiert Python ≥ 3.10 et PyTorch. L’installation est légère (la bibliothèque elle-même pèse quelques Mo) : ce sont les modèles téléchargés qui occupent l’espace disque (2-20 Go par modèle selon l’architecture). Les modèles sont mis en cache dans ~/.cache/huggingface/ et partagés entre toutes les utilisations.
Exemple : Text-to-Image (SDXL)
from diffusers import AutoPipelineForText2Image
import torch
pipe = AutoPipelineForText2Image.from_pretrained(
"stabilityai/stable-diffusion-xl-base-1.0",
torch_dtype=torch.float16
).to("cuda")
pipe.enable_model_cpu_offload() # optimisation VRAM
image = pipe(
"a medieval castle at sunset, oil painting",
num_inference_steps=30,
guidance_scale=7.5
).images[0]
image.save("castle.png")Exemple : Image-to-Image
from diffusers import AutoPipelineForImage2Image
from diffusers.utils import load_image
pipe = AutoPipelineForImage2Image.from_pretrained(
"stabilityai/stable-diffusion-xl-base-1.0",
torch_dtype=torch.float16
).to("cuda")
init_image = load_image("photo.jpg").resize((1024, 1024))
image = pipe(
"watercolor painting style",
image=init_image,
strength=0.6
).images[0]
image.save("watercolor.png")Exemple : Inpainting
from diffusers import AutoPipelineForInpainting
from diffusers.utils import load_image
pipe = AutoPipelineForInpainting.from_pretrained(
"diffusers/stable-diffusion-xl-1.0-inpainting-0.1",
torch_dtype=torch.float16
).to("cuda")
image = load_image("photo.png")
mask = load_image("mask.png") # blanc = zone à remplir
result = pipe(
"a beautiful garden with roses",
image=image,
mask_image=mask
).images[0]
result.save("inpainted.png")Notez la cohérence de l’API : les trois tâches (txt2img, img2img, inpainting) utilisent la même structure AutoPipeline + from_pretrained + appel. C’est la force de l’abstraction Diffusers : changer de tâche ou de modèle ne nécessite que de modifier une ou deux lignes.
Modular Diffusers (nouveauté mars 2026)
La v0.37 a introduit « Modular Diffusers », une refonte architecturale majeure. Au lieu de pipelines monolithiques, les pipelines sont composés de « blocks » réutilisables et composables. Chaque block (text encoding, denoising, VAE decoding, etc.) est indépendant et interchangeable. Un ComponentsManager gère automatiquement la mémoire entre les pipelines, déchargeant les modèles inutilisés.
L’intégration Hub est poussée : les blocks personnalisés publiés sur le Hub fonctionnent instantanément dans n’importe quel pipeline. L’outil visuel Mellon génère automatiquement une interface nodale à partir des définitions de blocks, sans code UI. Cette évolution rapproche Diffusers de la philosophie modulaire de ComfyUI tout en restant une bibliothèque Python programmatique.
Le format Diffusers
Diffusers a introduit un format de stockage de modèles qui est devenu un standard de l’industrie. Au lieu d’un seul fichier monolithique (comme les fichiers .ckpt ou .safetensors d’A1111), un modèle au format Diffusers est un répertoire structuré contenant chaque composant dans un sous-dossier dédié : unet/, text_encoder/, vae/, scheduler/, tokenizer/, et un fichier model_index.json qui décrit l’assemblage.
Ce format apporte plusieurs avantages. Chaque composant peut être chargé et remplacé indépendamment : vous pouvez utiliser le VAE d’un modèle avec le U-Net d’un autre. Les métadonnées de configuration sont explicites et lisibles (JSON). La compatibilité avec le Hub Hugging Face est native. Et la conversion vers/depuis le format safetensors est gérée par des utilitaires intégrés.
Les modèles publiés sur Hugging Face par les créateurs (Stability AI, Black Forest Labs, Tencent pour Hunyuan) sont de plus en plus souvent distribués directement au format Diffusers. Les modèles communautaires de Civitai sont généralement au format safetensors (fichier unique), mais des utilitaires de conversion existent dans les deux directions.
Diffusers vs ComfyUI : quand utiliser quoi ?
| Critère | Diffusers | ComfyUI |
|---|---|---|
| Interface | Code Python (scripts, notebooks) | Interface nodale visuelle |
| Public | Développeurs, chercheurs, intégrateurs | Power users, artistes avancés |
| Flexibilité | Maximale (tout est modifiable en Python) | Très haute (graphe de nœuds) |
| Intégration | Intégrable dans n’importe quelle app Python | Standalone ou API |
| Support modèles | Premier jour (source officielle) | Premier jour (via backend Diffusers ou propre) |
| Entraînement | Scripts complets (DreamBooth, LoRA, ControlNet) | Pas d’entraînement natif |
| Production | Idéal (API, batch, automatisation) | Possible (API, mais plus complexe) |
Le verdict : Diffusers est le choix des développeurs qui intègrent la génération d’images dans des applications, des pipelines de production, ou des projets de recherche. ComfyUI est le choix des créateurs qui veulent une interface visuelle pour construire et itérer sur des workflows. Les deux sont complémentaires : ComfyUI utilise d’ailleurs Diffusers (ou des composants équivalents) comme backend. Si vous codez, utilisez Diffusers. Si vous créez visuellement, utilisez ComfyUI. Si vous faites les deux, vous utiliserez les deux.
Cas d’usage
Intégration dans des applications
Diffusers est le moyen standard d’ajouter la génération d’images IA à une application Python. Un serveur Flask/FastAPI avec Diffusers en backend peut exposer une API de génération d’images en production. C’est la base de nombreux services SaaS de génération d’images.
Recherche et expérimentation
La modularité de Diffusers permet de tester rapidement de nouvelles architectures, de nouveaux schedulers, ou de nouvelles techniques de conditionnement. Chaque composant est remplaçable, ce qui facilite les ablation studies et les comparaisons systématiques.
Entraînement de modèles personnalisés
Les scripts d’entraînement fournis (DreamBooth, LoRA, Textual Inversion, ControlNet) sont la méthode de référence pour le fine-tuning de modèles de diffusion. Ils sont documentés, testés, et compatibles avec Accelerate pour le multi-GPU.
Backend pour les interfaces graphiques
InvokeAI utilise Diffusers comme backend principal. De nombreux outils et services tiers (Replicate, Modal, RunPod templates) s’appuient sur Diffusers pour l’inférence. C’est la fondation invisible de l’écosystème IA générative.
Questions fréquentes sur Diffusers
Faut-il coder en Python pour utiliser Diffusers ?
Oui. Diffusers est une bibliothèque Python, pas une interface graphique. Si vous préférez une interface visuelle, utilisez AUTOMATIC1111, ComfyUI, Forge, InvokeAI ou Fooocus. Mais si vous êtes développeur, data scientist, ou chercheur, Diffusers offre le contrôle le plus complet et la flexibilité la plus large sur le processus de diffusion.
Quelle est la différence entre Diffusers et Stable Diffusion ?
Stable Diffusion est un modèle de diffusion (les poids entraînés + l’architecture). Diffusers est une bibliothèque logicielle qui sait charger et exécuter Stable Diffusion (et des dizaines d’autres modèles de diffusion). L’analogie : Stable Diffusion est le moteur, Diffusers est le châssis. Vous pouvez installer un moteur SD, SDXL, FLUX ou Wan dans le châssis Diffusers.
Diffusers est-il utilisé par les interfaces comme A1111 et ComfyUI ?
InvokeAI utilise directement Diffusers comme backend. A1111 et ComfyUI utilisent leurs propres backends (k-diffusion pour A1111, backend propriétaire pour ComfyUI), mais sont compatibles avec les modèles au format Diffusers. Les scripts d’entraînement de Diffusers (DreamBooth, LoRA, Textual Inversion) sont utilisés indépendamment de l’interface choisie pour l’inférence.
Comment réduire la VRAM avec Diffusers ?
Trois niveaux d’optimisation. Niveau 1 : utilisez torch_dtype=torch.float16 (réduit la VRAM de moitié). Niveau 2 : activez pipe.enable_model_cpu_offload() (déplace les composants inactifs sur CPU, perte de vitesse minimale). Niveau 3 : utilisez la quantization 4-bit ou 8-bit via BitsAndBytes ou GGUF (réduit drastiquement la VRAM, légère perte de qualité). Un GPU de 4 Go peut faire tourner SD 1.5 avec les optimisations de niveau 1-2. Un GPU de 8 Go gère SDXL. FLUX nécessite 6-8 Go avec quantization, 16 Go en FP16.
Diffusers supporte-t-il la génération vidéo ?
Oui. Diffusers supporte nativement Wan 2.1 (text-to-video, image-to-video, video-to-video), Cosmos Predict2, Hunyuan Video, LTX Video, AnimateDiff, et Stable Video Diffusion. Les pipelines vidéo suivent la même API que les pipelines image : chargez le modèle avec from_pretrained(), passez un prompt, et récupérez les frames vidéo. Le support vidéo est en expansion active à chaque release.