Install & Compatibility
Where this runs
tested against v0.40.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
5043MB installed
● package 5043MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DiffusionPipeline
✓ from diffusers import DiffusionPipeline
✗ from diffusers import DiffusionPipeline
Basic text-to-image. Always set torch_dtype. Use enable_model_cpu_offload() for limited VRAM.
from diffusers import DiffusionPipeline
import torch
# Text-to-image
pipe = DiffusionPipeline.from_pretrained(
'stable-diffusion-v1-5/stable-diffusion-v1-5',
torch_dtype=torch.float16
).to('cuda')
image = pipe('A cat wearing a hat').images[0]
image.save('output.png')
# Memory-efficient: CPU offload (requires accelerate)
pipe.enable_model_cpu_offload()
# FLUX (latest high-quality model)
flux_pipe = DiffusionPipeline.from_pretrained(
'black-forest-labs/FLUX.1-schnell',
torch_dtype=torch.bfloat16
).to('cuda')
image = flux_pipe(
'An astronaut riding a horse on Mars',
guidance_scale=0.,
num_inference_steps=4
).images[0]
Debug
Known issues
breakingNot setting torch_dtype=torch.float16 loads the model in float32, typically requiring 14GB+ VRAM for SD 1.5 and 40GB+ for SDXL. Causes immediate CUDA OOM on most consumer GPUs. The most common LLM-generated diffusers bug.fixAlways pass torch_dtype=torch.float16 (RTX 30xx and earlier) or torch_dtype=torch.bfloat16 (RTX 40xx / A100+) to from_pretrained().
affects: all
breakingcallback and callback_steps parameters deprecated across all pipelines. Raises FutureWarning now, will raise TypeError in future release.fixReplace with callback_on_step_end=fn and callback_on_step_end_tensor_inputs=['latents'].
affects: >= 0.26
breakingfrom_single_file() model config args (num_in_channels, scheduler_type, image_size, upcast_attention) deprecated since 0.28. These were SD-specific anti-patterns not supported in from_pretrained().fixPass a config= argument pointing to a Hub repo or local path instead. Remove per-component config args from the pipeline loading call.
affects: >= 0.28
breakingenable_model_cpu_offload() and enable_sequential_cpu_offload() require accelerate to be installed. Calling them without accelerate raises ImportError.fixpip install accelerate before calling any offload methods.
affects: all
gotchaModel hub IDs change over time. 'CompVis/stable-diffusion-v1-4' and 'runwayml/stable-diffusion-v1-5' are outdated hub IDs from early tutorials. The current canonical SD 1.5 repo is 'stable-diffusion-v1-5/stable-diffusion-v1-5'.fixUse the current model IDs from https://huggingface.co/models. Old hub IDs from 2022-2023 tutorials may be deleted or moved.
affects: all
gotchaPipeline output is always a dataclass, not a tensor. pipe(...).images returns a list of PIL Images, not a tensor. Accessing .images[0] gives the first PIL Image.fixUse pipe(...).images[0] for the first image. To get numpy: pipe(...).images[0] then np.array(image). To get tensor: torch.from_numpy(np.array(image)).
affects: all
gotchaUpgrading diffusers without matching transformers version can silently degrade output quality or cause errors. diffusers and transformers are tightly coupled — each diffusers release targets specific transformers versions.fixUpgrade both together: pip install -U diffusers transformers. Check release notes for minimum transformers version requirements.
affects: all
breakingInstalling `diffusers` versions that constrain `Pillow` to less than `10.0` (e.g., `diffusers<0.10.0`) will result in a build failure for `Pillow` on Python 3.13, specifically `KeyError: '__version__'`. Older `Pillow` versions are generally not compatible with Python 3.13's build environment.fixTo use `diffusers` on Python 3.13, install `diffusers>=0.10.0` (which allows `Pillow>=10.0`). If you must use an older `diffusers` version that requires `Pillow<10.0`, you will need to use an older Python version (e.g., Python 3.11 or 3.12) where `Pillow<10.0` can be built.
affects: diffusers<0.10.0 on Python 3.13
Upgrade
Version history
0.40.0latest on PyPI · released Aug 20, 2026
Audit
Dependencies
torchrequiredRequired. Not installed automatically with bare pip install diffusers.
transformersrequiredRequired for most pipelines (text encoders, tokenizers). Install separately.
acceleraterequiredRequired for enable_model_cpu_offload(), enable_sequential_cpu_offload(), device_map. Install separately.
safetensorsoptionalRecommended for loading .safetensors checkpoints.