{"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":[{"note":"Always specify torch_dtype=torch.float16 (or bfloat16 for Ampere+). Omitting it loads the full float32 model which requires ~14GB+ VRAM for SD 1.5.","wrong":"pipe = DiffusionPipeline.from_pretrained('stable-diffusion-v1-5/stable-diffusion-v1-5')\n# Missing torch_dtype=torch.float16 — loads in float32, ~14GB VRAM, OOM on most GPUs","symbol":"DiffusionPipeline","correct":"from diffusers import DiffusionPipeline\nimport torch\n\npipe = DiffusionPipeline.from_pretrained(\n    'stable-diffusion-v1-5/stable-diffusion-v1-5',\n    torch_dtype=torch.float16  # REQUIRED — omitting uses float32 and will OOM on most GPUs\n)\npipe = pipe.to('cuda')\nimage = pipe('An astronaut on Mars').images[0]"},{"note":"callback and callback_steps parameters deprecated across all pipelines. Replaced by callback_on_step_end and callback_on_step_end_tensor_inputs.","wrong":"image = pipe(\n    prompt,\n    callback=my_callback,    # deprecated\n    callback_steps=1         # deprecated\n).images[0]","symbol":"callback","correct":"def step_callback(pipe, step, timestep, callback_kwargs):\n    # process latents here\n    return callback_kwargs\n\nimage = pipe(\n    prompt,\n    callback_on_step_end=step_callback,\n    callback_on_step_end_tensor_inputs=['latents']\n).images[0]"}],"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,"last_verified":"2026-05-12T11:51:34.761Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install diffusers`","cause":"The 'diffusers' library is not installed in your current Python environment or is not accessible on the Python path.","error":"ModuleNotFoundError: No module named 'diffusers'"},{"fix":"Reduce batch size, lower image dimensions, enable CPU offloading (e.g., `pipe.enable_model_cpu_offload()`), or ensure `torch_dtype=torch.float16` or `torch.bfloat16` is set when loading the pipeline.","cause":"The GPU lacks sufficient memory to perform the operation, typically due to a large model, high image resolution, or excessive batch size.","error":"RuntimeError: CUDA out of memory. Tried to allocate ... MiB (GPU ...; ... GiB total capacity; ... GiB already allocated; ... bytes free; ... GiB reserved in total by PyTorch)"},{"fix":"Ensure your `diffusers` library is up-to-date (`pip install --upgrade diffusers`). For very new models, you might need to install from the main branch (`pip install git+https://github.com/huggingface/diffusers.git`).","cause":"The requested pipeline class, module, or function ('SomePipelineClass') is either not available in your installed `diffusers` version or its name/import path has changed in a breaking update.","error":"AttributeError: module 'diffusers' has no attribute 'SomePipelineClass'"},{"fix":"Clear the Hugging Face cache (`rm -rf ~/.cache/huggingface/hub`) and attempt to load the model again, verifying the model identifier is correct and you have a stable internet connection.","cause":"A critical model checkpoint file (`diffusion_pytorch_model.bin`) or other necessary assets are missing or corrupted in the Hugging Face cache or the specified local path, preventing the model from loading.","error":"OSError: Error no file named diffusion_pytorch_model.bin"},{"fix":"Update the import statement from `from diffusers.pipeline_utils import DiffusionPipeline` to `from diffusers import DiffusionPipeline`.","cause":"The internal import path for `pipeline_utils` (or components like `DiffusionPipeline` within it) has been refactored or moved in a newer version of the `diffusers` library.","error":"ModuleNotFoundError: No module named 'diffusers.pipeline_utils'"}],"ecosystem":"pypi","meta_description":null,"install_score":35,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.91,"mem_mb":32.4,"disk_size":"195.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.89,"mem_mb":32.3,"disk_size":"305.3M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"torch","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.44,"mem_mb":32.4,"disk_size":"192M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":15.81,"mem_mb":159.4,"disk_size":"4.8G"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"torch","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":10.94,"mem_mb":141.5,"disk_size":"4.7G"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.97,"mem_mb":35.9,"disk_size":"215.2M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.87,"mem_mb":35.8,"disk_size":"343.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"torch","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.37,"mem_mb":35.9,"disk_size":"212M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":20.69,"mem_mb":178.9,"disk_size":"4.9G"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"torch","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":15.45,"mem_mb":160.3,"disk_size":"4.8G"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.82,"mem_mb":35.5,"disk_size":"201.1M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.83,"mem_mb":35.4,"disk_size":"326.3M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"torch","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.81,"mem_mb":35.5,"disk_size":"197M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":21.28,"mem_mb":173,"disk_size":"4.9G"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"torch","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":14.91,"mem_mb":154.9,"disk_size":"4.8G"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.72,"mem_mb":36.9,"disk_size":"200.4M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"torch","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.86,"mem_mb":36.9,"disk_size":"197M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":18.69,"mem_mb":177.4,"disk_size":"4.9G"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"torch","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":13.5,"mem_mb":155.6,"disk_size":"4.8G"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.27,"mem_mb":31.1,"disk_size":"196.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.74,"mem_mb":24.3,"disk_size":"308.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"torch","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.9,"mem_mb":31.1,"disk_size":"196M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"torch","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}