{"id":217,"library":"diffusers","title":"Diffusers","description":"Hugging Face library for state-of-the-art diffusion models: Stable Diffusion, FLUX, SDXL, video generation, and more. Current version is 0.37.1. Core API: DiffusionPipeline.from_pretrained(). Always set torch_dtype=torch.float16 or bfloat16 — default float32 causes OOM on most GPUs.","status":"active","version":"0.37.1","language":"python","source_language":"en","source_url":"https://github.com/huggingface/diffusers/releases","tags":["diffusion","image-generation","stable-diffusion","flux","huggingface","text-to-image","video-generation"],"install":[{"cmd":"pip install diffusers","lang":"bash","label":"Standard (PyTorch required separately)"},{"cmd":"pip install diffusers[torch]","lang":"bash","label":"With PyTorch CPU"},{"cmd":"pip install diffusers transformers accelerate","lang":"bash","label":"Full recommended stack"}],"dependencies":[{"reason":"Required. Not installed automatically with bare pip install diffusers.","package":"torch","optional":false},{"reason":"Required for most pipelines (text encoders, tokenizers). Install separately.","package":"transformers","optional":false},{"reason":"Required for enable_model_cpu_offload(), enable_sequential_cpu_offload(), device_map. Install separately.","package":"accelerate","optional":false},{"reason":"Recommended for loading .safetensors checkpoints.","package":"safetensors","optional":true}],"imports":[{"wrong":"from diffusers import DiffusionPipeline","symbol":"DiffusionPipeline","correct":"from diffusers import DiffusionPipeline"}],"quickstart":{"code":"from diffusers import DiffusionPipeline\nimport torch\n\n# Text-to-image\npipe = DiffusionPipeline.from_pretrained(\n    'stable-diffusion-v1-5/stable-diffusion-v1-5',\n    torch_dtype=torch.float16\n).to('cuda')\nimage = pipe('A cat wearing a hat').images[0]\nimage.save('output.png')\n\n# Memory-efficient: CPU offload (requires accelerate)\npipe.enable_model_cpu_offload()\n\n# FLUX (latest high-quality model)\nflux_pipe = DiffusionPipeline.from_pretrained(\n    'black-forest-labs/FLUX.1-schnell',\n    torch_dtype=torch.bfloat16\n).to('cuda')\nimage = flux_pipe(\n    'An astronaut riding a horse on Mars',\n    guidance_scale=0.,\n    num_inference_steps=4\n).images[0]","lang":"python","description":"Basic text-to-image. Always set torch_dtype. Use enable_model_cpu_offload() for limited VRAM."},"warnings":[{"fix":"Always pass torch_dtype=torch.float16 (RTX 30xx and earlier) or torch_dtype=torch.bfloat16 (RTX 40xx / A100+) to from_pretrained().","message":"Not 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.","severity":"breaking","affected_versions":"all"},{"fix":"Replace with callback_on_step_end=fn and callback_on_step_end_tensor_inputs=['latents'].","message":"callback and callback_steps parameters deprecated across all pipelines. Raises FutureWarning now, will raise TypeError in future release.","severity":"breaking","affected_versions":">= 0.26"},{"fix":"Pass a config= argument pointing to a Hub repo or local path instead. Remove per-component config args from the pipeline loading call.","message":"from_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().","severity":"breaking","affected_versions":">= 0.28"},{"fix":"pip install accelerate before calling any offload methods.","message":"enable_model_cpu_offload() and enable_sequential_cpu_offload() require accelerate to be installed. Calling them without accelerate raises ImportError.","severity":"breaking","affected_versions":"all"},{"fix":"Use the current model IDs from https://huggingface.co/models. Old hub IDs from 2022-2023 tutorials may be deleted or moved.","message":"Model 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'.","severity":"gotcha","affected_versions":"all"},{"fix":"Use 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)).","message":"Pipeline 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.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade both together: pip install -U diffusers transformers. Check release notes for minimum transformers version requirements.","message":"Upgrading 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.","severity":"gotcha","affected_versions":"all"},{"fix":"To 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.","message":"Installing `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.","severity":"breaking","affected_versions":"diffusers<0.10.0 on Python 3.13"}],"env_vars":null,"search_vec":"'0.37.1':24 'alway':29 'api':26 'art':10 'bfloat16':35 'caus':38 'core':25 'current':21 'default':36 'diffus':1,11,14,43,49 'diffusionpipeline.from':27 'dtype':32 'face':3 'float32':37 'flux':15,50 'generat':18,46,58 'gpus':42 'hug':2 'huggingfac':51 'imag':45,55 'image-gener':44 'librari':4 'model':12 'oom':39 'pretrain':28 'sdxl':16 'set':30 'stabl':13,48 'stable-diffus':47 'state':7 'state-of-the-art':6 'text':53 'text-to-imag':52 'torch':31 'torch.float16':33 'version':22 'video':17,57 'video-gener':56","created_at":"2026-03-26T04:37:52.261046+00:00","updated_at":"2026-04-16T06:25:53.516641+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":35,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"0.40.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://huggingface.co/docs/diffusers","github":"https://github.com/huggingface/diffusers","docs":null,"changelog":null,"pypi":"https://pypi.org/project/diffusers/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","llm-agents"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-08-27","next_check":"2026-08-02","install_tag":"stale"}}