NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #1669 most downloaded on PyPI
State-of-the-art diffusion in PyTorch.
Latest stable
0.42.1
Last release 26 days ago
27 Oct 2026
Ships fairly regularly
a new release about every 2 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
4 years old
102 releases · first in 2022
Drag across the ruler to compare, or tap a release to open it.
This is a security release. See GHSA-4prv-5hj7-c2xr for details.
This is a security release. See GHSA-4prv-5hj7-c2xr for details.
This patch release fixes how a component's declared library name is resolved when loading with from_pretrained.
Pipelines and models declare each component as a ["<library>", "<class>"] pair in model_index.json / config.json. This release changes how that library name is resolved across the DiffusionPipeline, AutoModel, and ModularPipeline loading paths, and adds a clearer error when the declared class is not found in the resolved module.
All users on 0.42.0 are encouraged to upgrade:
pip install diffusers==0.42.1
v0.42.1 — fix component resolution in from_pretrained to prevent trust_remote_code bypass
Compare
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Custom workflows should pass unpacked latents to their decode blocks. The fallback for packed latents is deprecated for removal in 0.47.0.
[!TIP] This release brings FLUX.3 Image Klein, Bria Fibo 2.0, Kandinsky 6, SANA-WM, and RFD4-Proteína to Diffusers, alongside new adapter support, hardware integrations, and modular pipelines. 🚨 Python 3.11 or newer is now required.
FLUX.3 Image Klein from Black Forest Labs supports text-to-image generation and editing with one or more reference images. Both the base and step-distilled checkpoints are available through ModularPipeline, with an integrated prompt upsampler that turns short requests into detailed captions and supports layout instructions with bounding boxes. The integration also includes single-file transformer loading and BFL FP8r and NVFP4 checkpoints.
Load the pipeline with ModularPipeline.from_pretrained(...), then load its weights with load_components(...). See the FLUX.3 documentation for examples and guidance on prompt upsampling, editing, and memory use.
Bria Fibo 2.0 supports image generation from structured JSON captions and editing with up to five reference images through BriaFibo2Pipeline. The integration includes the dev checkpoint and the edit-turbo checkpoint, which runs in four steps without classifier-free guidance. See the Fibo 2.0 documentation for the supported prompt formats.
LoRA loading and DreamBooth LoRA training examples are included for text-to-image and image editing. Thanks to @muhammadali-afridi for the model integration (#14991).
Kandinsky 6 generates video with synchronized audio from text or a reference image through Kandinsky6TI2VAPipeline. A separate Kandinsky6SRPipeline provides video super-resolution. The integration supports Pro and Lite generation checkpoints, including distilled variants, and introduces PiflowScheduler for the distilled models. See the Kandinsky 6 documentation for checkpoint-specific settings and super-resolution requirements. Thanks to @lefff for the model integration (#14949).
SANA-WM generates video from a starting image, a text prompt, and a camera trajectory. Control the camera with explicit poses or a WASD/IJKL action string, then optionally refine the output with the separate LTX-2 refiner. See the SANA-WM documentation for the two-stage workflow.
Thanks to @lawrence-cj for the integration (#13881).
RFD4-Proteína from the Baker Lab and NVIDIA brings biomolecular design to Diffusers. It jointly generates protein sequences and all-atom structures while conditioning on molecular context such as binding targets, motifs, or ligands. The integration includes the pipeline, transformer, autoencoder, schedulers, and LoRA loading. Preparing model inputs and writing CIF files uses the separate rfd4-proteina-prep package; see the RFD4-Proteína documentation.
Thanks to @kierandidi for the integration (#15088).
torch.compile, and tensor parallelism. Tensor parallelism also gains Intel XPU support. (#14039, #15013)motion_speed controls the positional time base independently of playback frame rate. Use a compatible adapter for speeds far from the default, such as the LTX-2.5 slow-motion control LoRA. (#14967)AutoencoderKLKVAEAudio adds encoding and decoding for 48 kHz audio. (#14384)joint_attention_kwargs, Qwen-Image applies .alpha scaling to lora_A/lora_B checkpoints, and text encoders correctly report active adapters. (#15015, #15016, #14961)FlowMatchEulerDiscreteScheduler, fix Anima text encoder exports and standalone core denoising, and preserve the three-value return from InpaintProcessor.preprocess when no mask is supplied. (#14956, #14943, #14481)huggingface_hub range is now >=1.32.0,<3.0. (#14863)Thanks to everyone who contributed to this release!
custom_blocks by @yiyixuxu in #15001test_modeling_common.py by @DN6 in #14988motion_speed to condition the positional time base apart from the playback frame rate by @christopher5106 in #14967The following contributors added models and capabilities in this release:
Full changelog: v0.41.0 to the v0.42.0 release commit
Diffusers 0.42.0: FLUX.3, Fibo 2.0, Kandinsky 6, and more
Compare
🚨 ONNX support is deprecated; use Optimum for ONNX Runtime workflows.
[!TIP] This release brings Qwen-Image 2.1 to Diffusers, with text-to-image generation, image editing, native transparency, and LoRA training.
Starting with this release, we’re adopting the Transformers release philosophy: coordinating minor releases around new model integrations, while including the other changes merged since the previous release. Patch releases remain focused on fixes. See our release policy.
Qwen-Image 2.1 unifies image generation and editing in one model. Its visual generation component has 7B parameters, and it supports multiple reference images and native RGBA output for transparent images. Check out the docs for more details.
Thanks to @naykun for the model integration (#14804).
Other highlights
test_pipelines_common.py test suite to establish more modularity and transparent implementation of tests. Refer to https://github.com/huggingface/diffusers/pull/14669/ for more details.Deprecations and compatibility
🚨 ONNX support is deprecated; use Optimum for ONNX Runtime workflows. (#14658)
Previously deprecated APIs have been removed, including the LuminaText2ImgPipeline and Lumina2Text2ImgPipeline aliases. Use LuminaPipeline and Lumina2Pipeline instead. Older integrations should review the removed code paths before upgrading.
Thanks to everyone who contributed to this release!
test_pipelines.py to use pytest. by @sayakpaul in #14222LTX2Guidance Guider to guiders/ Folder by @dg845 in #14558overwrite_modular_index to be True by @yiyixuxu in #14659@diffusers-bot by @DN6 in #14623test_pipelines_common.py by @sayakpaul in #14669The following contributors have made significant changes to the library over the last release:
LTX2Guidance Guider to guiders/ Folder (#14558)Diffusers 0.41.0: QwenImage 2.1 pipeline and more
Compare
`torch_dtype` is deprecated in favour of `dtype` (#14205, #14313), following transformers. torch_dtype still works but warns, and will be removed in 1…
[!TIP] This release features several new pipelines, including LTX2.5, MiniMax H3, and Wan Animate 2. We're also graduating Modular Diffusers out of the experimental phase and announcing its stable support. Additionally, this release includes minimal support for tensor-parallel. There's a lot more that went down in this release. So, please consult the notes for details.
MiniMax-H3 generates video and its soundtrack together. A single transformer denoises one packed sequence containing the text conditioning, the conditioning media, and the target video and audio latents — there is no separate vocoder and no post-hoc audio pass. Its conditioner is a Qwen3VLForConditionalGeneration whose unnormalized 50th-decoder-layer hidden state is read instead of the last one.
MiniMax-H3 is integrated as Modular Diffusers blocks only — MiniMaxH3Blocks and their MiniMaxH3ModularPipeline are the whole integration. The conversion ships both checkpoint partitions in one repository and exposes three workflows (t2va, fl2va, ref2va) that can be pruned at from_pretrained time so only that task's components are declared and downloaded.
MiniMax Music 3 produces complete songs up to five minutes long from lyrics and a music description, with expressive vocals and long-range structure. It is a hybrid of an autoregressive and a diffusion stage: an 8B Qwen3-based global language model predicts one semantic audio token per frame while a small depth decoder fills in seven residual RVQ codebooks, and their fused hidden states condition a 2.4B flow-matching transformer that produces Flow-VAE latents in overlapping chunks. A DAC-style decoder turns the latents into 44.1 kHz stereo audio.
Stable Audio 3 is a text-to-audio model from Stability AI that generates high-quality stereo audio at 44.1 kHz. It uses a rectified-flow DiT conditioned on a frozen T5Gemma text encoder (via cross-attention) and on duration (a float embedded by StableAudio3DurationEmbedder and used for adaptive layer norm), and decodes with the SAME (Semantically-Aligned Music Encoder) autoencoder, AutoencoderSAME.
Three pipelines ship: StableAudio3Pipeline, StableAudio3AudioToAudioPipeline, and StableAudio3InpaintPipeline.
Thanks to @buffett0323 for the contribution (https://github.com/huggingface/diffusers/pull/14119).
LTX-2.5 reuses the existing LTX2Pipeline / LTX2VideoTransformer3DModel / AutoencoderKLLTX2Video classes — there is no separate pipeline class. The user-visible difference is the text encoder: LTX-2.5 is paired with a Gemma 4 (gemma4_unified) checkpoint, loaded automatically from a converted LTX-2.5 repo.
Lightricks/LTX-2.5-Diffusers ships both the distilled DiT (transformer/) and the full/SFT DiT (transformer_full/), plus everything two-stage generation needs. Alongside the checkpoint support, this release adds:
LTX2VideoDiffusionDecoderModel and LTX2VideoDiffusionDecodePipeline — a second video decoder over the same latent space, so latents are interchangeable between decoders.duration_head that predicts shot length from the text-connector output, so num_frames is auto-predicted by default when the loaded pipeline has one.google/gemma-4-E2B-it checkpoint (enable_prompt_enhancement=True).LTX25AutoBlocks for Modular Diffusers (#14453).Wan-Animate-2 by the Alibaba Wan Team animates a reference character image with the motion of a driving video. The driving video is processed in fixed-length segments: each segment runs a reference-extraction pass that caches the driving segment's K/V in every transformer layer, denoises against that cache, and is decoded inside the loop, because the next segment conditions on the previous segment's decoded tail frames.
Two presets are available — the base checkpoint samples with classifier-free guidance, and the distilled checkpoint samples in few steps without it. Guidance is owned by the pipeline's guider component, so there is no guidance_scale argument.
Thanks to @kelseyee for authoring the integration (https://github.com/huggingface/diffusers/pull/14413).
JoyAI-Image-Edit-Plus extends the JoyAI-Image family (an 8B MLLM paired with a 16B MMDiT) to multi-image instruction-guided editing. It accepts 1–5 reference images plus a text instruction and composes elements from the references into a new image.
Thanks to @tangyanf for the contribution (https://github.com/huggingface/diffusers/pull/14032).
Cosmos 3 landed in 0.39.0 and gets substantially more coverage in this release:
Cosmos3OmniModularPipeline), with Transfer support for precomputed control videos (edge, blur, depth, segmentation, world-scenario maps) generated autoregressively in chunks and stitched automatically.Cosmos3DistilledModularPipeline.Thanks to @yzhautouskay and @atharvajoshi10 for the contributions.
Modular Diffusers is no longer marked experimental (#14525) — the API warning has been dropped.
DiffusionPipeline half.ConditionalPipelineBlocks declare different defaults for the same input, combine_inputs now merges the default to None and records the per-block defaults in a new InputParam.defaults_by_block field. get_block_state falls back to the block's own declared default, so each branch resolves its own default when it actually runs. Docstrings render conflicted defaults as e.g. "defaults to None or 189, depending on the workflow".intermediate_inputs were cleaned up, stale auto-docstrings are now detected in CI, and Mellon custom-block required-input handling was fixed.[!IMPORTANT] Please try out Modular Diffusers and let us know about your feedback!
Tensor-parallel inference is now supported for model inference on CUDA and AWS Neuron (Trainium/Inferentia), exposed through the same public API already used for context parallelism:
from diffusers import TensorParallelConfig
pipe.transformer.enable_parallelism(config=TensorParallelConfig(mesh=tp_mesh))
Sharding is model-agnostic and driven from a flat _tp_plan, which has been added to the FLUX.1, FLUX.2 and Qwen-Image DiTs. Check out the docs for more details.
kernels-community/aiter-flash-attn-ck Hub kernel, dropping the aiter dependency. Thanks to @Abdennacer-Badaoui._flash_3_varlen_hub backend and a mask-handling fix. Thanks to @zhtmike.DiffusionPipeline.device deduction for split-device pipelinesThe diffusers-cli was reworked for agentic use (#13966) and then cleaned up (#14381): modular_model_index.json is written when saving a custom block so ModularPipeline.from_pretrained can load and run custom blocks as pipelines, auto CPU offload works for Modular pipelines, workflow can be passed to Modular pipelines, and output saving handles multimodal output (e.g. LTX video frames + audio) and batched video.
Skills are now installed through the CLI rather than the Makefile (#14454):
diffusers-cli skills list
diffusers-cli skills add <skill name>
Flax* classes and the flax extras are gone.get_peft_kwargs took lora_alpha from the first entry of the rank dict and never revisited it, so every module whose rank differed from the first key's rank got an arbitrary, key-order-dependent scale. Ranks are now mirrored into the alphas when a checkpoint brings no alpha information (the diffusers/PEFT convention: alpha == rank, scale 1.0). Adapters with a declared alpha keep it, and uniform-rank adapters are unaffected. Existing mixed-rank, no-alpha LoRAs will now produce different (correct) results.torch_dtype is deprecated in favour of dtype (#14205, #14313), following transformers. torch_dtype still works but warns, and will be removed in 1.0.0. A torch.dtype alias was added for the docs.dduf_file warns and will be removed in 0.41.0.SECURITY.md was added.different_shapes_for_compilation. Thanks to @jiqing-feng._merged_adapters when it is unfused from all components.visual_cond channels.WanTransformer3DModel and SD3Transformer2DModel hidden states contiguoussnapshot_download with the latest huggingface_hubA large chunk of this release is test modernization: pipeline tests continue migrating to the new mixin structure (Wan, Qwen-Image, FLUX.2, CogVideoX, Stable Diffusion, and the LoRA pipeline tests), tests/others, training tests, and attention-processor tests moved to pytest, model-level and pipeline-level quantization tests were standardized, and an output_shape property was introduced in the pipeline tests. The agent-facing docs and skills under .ai/ were expanded to cover tests, model implementation, and blockset conventions.
_flash_3_varlen_hub mask handling by @zhtmike in #14115_flash_3_varlen_hub backend by @zhtmike in #13809SD3Transformer2DModel hidden states contiguous by @menglcai in #14186kwargs_type input/output by @yiyixuxu in #14157WanTransformer3DModel hidden states contiguous before the block loop by @menglcai in #14236torch_dtype and prefer dtype following transformers. by @sayakpaul in #14205diffusers-cli for agentic use by @DN6 in #13966different_shapes_for_compilation by @jiqing-feng in #14297Args: entries to scheduler docstrings by @4ktLuffy in #14354SlowBnb4BitFluxControlWithLoraTests::test_lora_loading by @jiqing-feng in #14202tests/others to pytest. by @sayakpaul in #14299output_shape property in the pipeline tests. by @sayakpaul in #14253unload_components() by @sayakpaul in #14406DiffusionPipeline.device deduction for split-device pipelines by @JingyaHuang in #14383LTX25AutoBlocks to new file with new model name by @dg845 in #14453kernels-community/aiter-flash-attn-ck Hub kernel for ROCm FlashAttention (drop aiter dependency) by @Abdennacer-Badaoui in #14436Diffusers 0.40.0: New pipelines, tensor-parallel support, improved CLI, and more
Compare
Cosmos 3 is NVIDIA's unified world foundation model (WFM) for Physical AI — a single omni-model built on a Mixture-of-Transformers (MoT) architecture
Cosmos 3 is NVIDIA's unified world foundation model (WFM) for Physical AI — a single omni-model built on a Mixture-of-Transformers (MoT) architecture that combines world generation, physical reasoning, and action generation, replacing the separate Predict, Reason, and Transfer models from earlier Cosmos releases. A single Cosmos3OmniTransformer runs a Qwen-style language model in parallel with a diffusion generation pathway, joined by a 3D multimodal RoPE. This release also lands video-to-video and action-conditioned generation, and a sound encoder.
Thanks to @atharvajoshi10, @yzhautouskay, and @MaciejBalaNV for the contributions.
Ideogram 4 is a flow-matching text-to-image model that uses a multimodal text encoder and an asymmetric classifier-free guidance scheme: a dedicated unconditional_transformer produces the negative branch with zeroed text features, while the main transformer consumes the full packed text + image sequence. The pipeline ships with structured prompt upsampling and LoRA loading support.
Thanks to @JinLiIdeogram for the contribution.
Krea 2 (K2) is a flow-matching text-to-image model built around a single-stream MMDiT with grouped-query attention. A Qwen3-VL text encoder provides the conditioning — hidden states from twelve decoder layers are tapped per token and fused inside the transformer by a small text-fusion stage — and images are decoded with the Qwen-Image VAE. Both the base (midtrain) and TDM (distilled, few-step) checkpoints are supported, alongside a LoRA DreamBooth trainer.
Thanks to @EleaZhong and @Abhinay1997 for the contribution.
DreamLite is a text-to-image and image-editing model from ByteDance. It pairs a custom 2D U-Net (DreamLiteUNetModel) with the Qwen3-VL multimodal encoder as its prompt / image-instruction encoder, and uses an AutoencoderTiny (TAESD-style) VAE for fast latent encode/decode. A distilled DreamLiteMobilePipeline targets on-device, low-latency generation.
Thanks to @Carlofkl for the contribution.
PRXPixel is a pixel-space text-to-image generation model by Photoroom. A ~7B PRXTransformer2DModel denoises raw RGB images directly — no VAE is needed. The model is conditioned on a Qwen3-VL text encoder and uses flow matching where the transformer predicts the clean image at each step (x-prediction).
Thanks to @DavidBert for the contribution.
Motif-Video is a 2B parameter diffusion transformer for text-to-video and image-to-video generation. It features a three-stage architecture (12 dual-stream + 16 single-stream + 8 DDT decoder layers), Shared Cross-Attention for stable text-video alignment over long sequences, a T5Gemma2 text encoder, and rectified flow matching for velocity prediction.
Thanks to @waitingcheung for the contribution.
AnyFlow from NVIDIA, NUS, and MIT is the first any-step video diffusion framework built on flow maps, enabling a single model (bidirectional or causal) to adapt to arbitrary inference budgets. It ships both bidirectional and FAR causal pipelines built on Wan2.1 backbones, covering text-to-video, image-to-video, and video-to-video.
Thanks to @Enderfga for the contribution.
JoyAI-Image is a unified multimodal foundation model for image understanding, text-to-image generation, and instruction-guided image editing. It combines an 8B Multimodal LLM with a 16B Multimodal Diffusion Transformer (MMDiT). JoyImageEditPipeline supports general image editing as well as spatial editing capabilities including object move, object rotation, and camera control.
Thanks to @Moran232 for the contribution.
DiffusionGemma is a block-diffusion encoder-decoder language model. A causal encoder reads the clean prompt (and any previously generated blocks) into a KV cache, and a bidirectional decoder denoises a fixed-size "canvas" of tokens by cross-attending to that cache, committing the most confident tokens via the new BlockRefinementScheduler. The released checkpoint is google/diffusiongemma-26B-A4B-it.
Anima is a 2 billion parameter text-to-image model created via a collaboration between CircleStone Labs and Comfy Org. It is focused mainly on anime concepts, characters, and styles, but is also capable of generating a wide variety of other non-photorealistic content.
It reuses the CosmosTransformer3DModel with a Qwen3 text encoder, a T5-token text conditioner, and the AutoencoderKLQwenImage VAE.
Thanks to @rmatif for the contribution.
New LTX2InContextPipeline (in-context LoRA) and LTX2HDRPipeline extend the LTX-2 family with in-context conditioning and HDR video generation.
ErnieImageModularPipeline (#13948) and Ideogram4ModularPipeline (#13980), thanks to @SamuelTallet._dequantize for the TorchAO quantizerAutoPipelineForText2Audiotorch.compile compatibilitysafetensors to 0.8.0torch version is now 2.6txt_seq_lens from qwen transformer. by @sayakpaul in #13674torch.distributed by @hlky in #13673flash_varlen_hub backend by @zhtmike in #13479transformers from main for doc and staging by @sayakpaul in #13723modules_to_not_convert / keep_in_fp32_modules by @dg845 in #13697weighting chunk when using prior preservation in Flux and SD3 LoRA training by @Dev-X25874 in #13743torch_device import in AutoencoderTesterMixin by @DN6 in #13852device_map="auto" in single file tests to support large models on limited GPU memory by @jiqing-feng in #13816cond_model_input in Flux2 Klein img2img training by @HaozheZhang6 in #13923ErnieImageModularPipeline by @SamuelTallet in #13948AutoModel by @neo in #13889Ideogram4ModularPipeline by @SamuelTallet in #13980torch.compile compatibility with Neuron device by @JingyaHuang in #13485Ideogram4MRoPE collapsing under torch.autocast (compute rotary in float32) by @HaozheZhang6 in #13922The following contributors have made significant changes to the library over the last release:
torch_device import in AutoencoderTesterMixin (#13852)modules_to_not_convert / keep_in_fp32_modules (#13697)torch.compile compatibility with Neuron device (#13485)Diffusers 0.39.0: New image and video pipelines, core library improvements, and more
Compare
One column per quarter.