# huggingface/diffusers architecture

> Architecture diagram of the GitHub repository huggingface/diffusers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huggingface/diffusers
- Repository: https://github.com/huggingface/diffusers

## Overview

Diffusers is a Python library for loading and composing pretrained diffusion components to generate image, audio, video, and other outputs. Its main workflow is user → pipeline loading → iterative denoising with a model and scheduler → decoded result. The README also documents lower-level model/scheduler composition and modular pipelines. The tree and sampled files support these major branches, but do not establish every pipeline’s internal call sequence; edges reflect README statements or visible references, not an assumed execution order.

Main entry points: [`src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_inpaint.py`](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_inpaint.py) (Diffusion pipeline), [`src/diffusers/models/modeling_utils.py`](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/modeling_utils.py) (Pretrained models), [`src/diffusers/pipelines/pipeline_utils.py`](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py) (Pipeline loader), [`src/diffusers/pipelines/auto_pipeline.py`](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/auto_pipeline.py) (Pipeline selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inference["Inference workflows"]
  node_loader["Pipeline loader<br/>[pipeline_utils.py]"]
  node_auto["Pipeline selection<br/>[auto_pipeline.py]"]
  node_pipeline["Diffusion pipeline"]
  node_modular["Modular pipelines"]
  node_result["Generated outputs"]
end

subgraph group_components["Diffusion components"]
  node_models["Pretrained models<br/>[modeling_utils.py]"]
  node_transformers["Denoising networks<br/>[transformer_2d.py]"]
  node_autoencoders["Autoencoders<br/>[autoencoder_kl.py]"]
  node_schedulers["Noise schedulers<br/>[__init__.py]"]
  node_image["Image processing<br/>[image_processor.py]"]
end

subgraph group_customization["Customization and optimization"]
  node_weights["Pretrained weights<br/>[single_file.py]"]
  node_adapters["Adapter loading<br/>[lora_pipeline.py]"]
  node_hooks["Runtime optimization"]
  node_callbacks["Step callbacks<br/>[callbacks.py]"]
end

subgraph group_foundation["Shared runtime"]
  node_config["Configuration"]
  node_utils["Tensor utilities<br/>[torch_utils.py]"]
end

node_user(("Library user"))

node_user -->|"loads pretrained"| node_loader
node_loader -->|"loads components"| node_pipeline
node_user -->|"selects pipeline"| node_auto
node_auto -->|"resolves pipeline"| node_pipeline
node_user -->|"runs inference"| node_pipeline
node_pipeline -->|"returns output"| node_result
node_user -->|"builds diffusion system"| node_models
node_user -->|"chooses scheduler"| node_schedulers
node_pipeline -->|"uses model components"| node_models
node_pipeline -->|"uses scheduler"| node_schedulers
node_pipeline -->|"processes images"| node_image
node_models -.->|"includes denoisers"| node_transformers
node_models -.->|"includes decoders"| node_autoencoders
node_user -->|"builds modular system"| node_modular
node_user -.->|"loads model weights"| node_weights
node_user -.->|"adds adapters"| node_adapters
node_user -.->|"optimizes execution"| node_hooks
node_pipeline -.->|"supports callbacks"| node_callbacks
node_models -->|"serializes configuration"| node_config
node_pipeline -->|"uses tensor helpers"| node_utils

click node_loader "https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py"
click node_auto "https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/auto_pipeline.py"
click node_pipeline "https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_inpaint.py"
click node_modular "https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline.py"
click node_result "https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_inpaint.py"
click node_models "https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/modeling_utils.py"
click node_transformers "https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_2d.py"
click node_autoencoders "https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_kl.py"
click node_schedulers "https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/__init__.py"
click node_image "https://github.com/huggingface/diffusers/blob/main/src/diffusers/image_processor.py"
click node_weights "https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/single_file.py"
click node_adapters "https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/lora_pipeline.py"
click node_hooks "https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/group_offloading.py"
click node_callbacks "https://github.com/huggingface/diffusers/blob/main/src/diffusers/callbacks.py"
click node_config "https://github.com/huggingface/diffusers/blob/main/src/diffusers/configuration_utils.py"
click node_utils "https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_loader,node_auto,node_pipeline,node_modular,node_result,node_user toneBlue
class node_models,node_transformers,node_autoencoders,node_schedulers,node_image toneAmber
class node_weights,node_adapters,node_hooks,node_callbacks toneMint
class node_config,node_utils toneRose
```

## Components

### Inference workflows

- [Pipeline loader](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py): `src/diffusers/pipelines/pipeline_utils.py`
- [Pipeline selection](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/auto_pipeline.py): `src/diffusers/pipelines/auto_pipeline.py`
- [Diffusion pipeline](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_inpaint.py): `src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_inpaint.py`
- [Modular pipelines](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline.py): `src/diffusers/modular_pipelines/modular_pipeline.py`
- [Generated outputs](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_inpaint.py): `src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_inpaint.py`

### Diffusion components

- [Pretrained models](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/modeling_utils.py): `src/diffusers/models/modeling_utils.py`
- [Denoising networks](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_2d.py): `src/diffusers/models/transformers/transformer_2d.py`
- [Autoencoders](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_kl.py): `src/diffusers/models/autoencoders/autoencoder_kl.py`
- [Noise schedulers](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/__init__.py): `src/diffusers/schedulers/__init__.py`
- [Image processing](https://github.com/huggingface/diffusers/blob/main/src/diffusers/image_processor.py): `src/diffusers/image_processor.py`

### Customization and optimization

- [Pretrained weights](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/single_file.py): `src/diffusers/loaders/single_file.py`
- [Adapter loading](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/lora_pipeline.py): `src/diffusers/loaders/lora_pipeline.py`
- [Runtime optimization](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/group_offloading.py): `src/diffusers/hooks/group_offloading.py`
- [Step callbacks](https://github.com/huggingface/diffusers/blob/main/src/diffusers/callbacks.py): `src/diffusers/callbacks.py`

### Shared runtime

- [Configuration](https://github.com/huggingface/diffusers/blob/main/src/diffusers/configuration_utils.py): `src/diffusers/configuration_utils.py`
- [Tensor utilities](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py): `src/diffusers/utils/torch_utils.py`

### Other components

- **Library user**

## Connections

- Library user → Pipeline loader: loads pretrained (evidence: `README.md`)
- Pipeline loader → Diffusion pipeline: loads components (evidence: `src/diffusers/pipelines/pipeline_utils.py`)
- Library user → Pipeline selection: selects pipeline (evidence: `README.md`)
- Pipeline selection → Diffusion pipeline: resolves pipeline (evidence: `src/diffusers/pipelines/auto_pipeline.py`)
- Library user → Diffusion pipeline: runs inference (evidence: `README.md`)
- Diffusion pipeline → Generated outputs: returns output (evidence: `README.md`)
- Library user → Pretrained models: builds diffusion system (evidence: `README.md`)
- Library user → Noise schedulers: chooses scheduler (evidence: `README.md`)
- Diffusion pipeline → Pretrained models: uses model components (evidence: `src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_inpaint.py`)
- Diffusion pipeline → Noise schedulers: uses scheduler (evidence: `src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_inpaint.py`)
- Diffusion pipeline → Image processing: processes images (evidence: `src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_inpaint.py`)
- Pretrained models → Denoising networks: includes denoisers
- Pretrained models → Autoencoders: includes decoders
- Library user → Modular pipelines: builds modular system (evidence: `README.md`)
- Library user → Pretrained weights: loads model weights
- Library user → Adapter loading: adds adapters
- Library user → Runtime optimization: optimizes execution
- Diffusion pipeline → Step callbacks: supports callbacks (evidence: `src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_inpaint.py`)
- Pretrained models → Configuration: serializes configuration (evidence: `src/diffusers/configuration_utils.py`)
- Diffusion pipeline → Tensor utilities: uses tensor helpers (evidence: `src/diffusers/utils/torch_utils.py`)
