# custom-blocks

Adopt this skill: https://proskills.md/skills/other/huggingface-diffusers-ai-skills-custom-blocks

Page: https://proskills.md/skills/other/huggingface-diffusers-ai-skills-custom-blocks
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .ai/skills/custom-blocks/SKILL.md
size: 6945
upstream: https://github.com/huggingface/diffusers/blob/main/.ai/skills/custom-blocks/SKILL.md

````text
---
name: custom-blocks
description: >
  Use when the user has written (or wants to write) a `ModularPipelineBlocks`
  subclass in a local Python file and needs to package it into a Hub-uploadable
  directory. Covers the workflow from a single `block.py` file to a published
  custom-block repo that consumers can load via
  `ModularPipeline.from_pretrained(<repo>, trust_remote_code=True)`.
---

## What this skill is for

A `ModularPipelineBlocks` subclass is a unit of pipeline logic — input/output spec plus a `__call__` — that
slots into diffusers' modular pipeline composition. Once you have one defined locally, you almost always want to
publish it as a small Hub repo so others can `from_pretrained` it. `diffusers-cli custom_blocks` automates the
packaging step: it parses your Python file, instantiates the chosen block class, and writes a
`save_pretrained`-style directory in your cwd that's ready to push to the Hub.

Use this skill when:

- The user is writing a custom modular block and asks "how do I publish this?" or "package this for the Hub".
- The user has a `block.py` (or similar) file with one or more `ModularPipelineBlocks` subclasses.
- You're scaffolding a new modular pipeline repo and need the on-disk layout that `ModularPipelineBlocks.from_pretrained`
  expects.

Don't use this skill for: running an existing modular pipeline (`diffusers-cli run`), introspecting one
(`diffusers-cli schema`), or writing the block class itself — this skill packages an *already-written* block.

## The end-to-end workflow

```
[you: write block.py] → diffusers-cli custom_blocks → [packaged dir in cwd]
                                                            ↓
                                            hf upload <repo> .
                                                            ↓
                                consumers: ModularPipeline.from_pretrained(<repo>, trust_remote_code=True)
                                           diffusers-cli schema --model <repo> --trust-remote-code
                                           diffusers-cli run --model <repo> --trust-remote-code ...
```

The skill covers the middle box. The bookends (writing the block and uploading) are out of scope.

## Command surface

```bash
diffusers-cli custom_blocks [--block_module_name <file.py>] [--block_class_name <ClassName>]
```

### Flags

- `--block_module_name <file>` — Python file containing the block class. Defaults to `block.py` in the cwd.
- `--block_class_name <name>` — Which class in the file to package. Optional: if omitted, the CLI parses the
  file with `ast`, finds every class that inherits from `ModularPipelineBlocks`, and uses the first one (with
  an info log naming the others). Specify explicitly when the file defines more than one block and you want a
  specific one.

### What it does

1. **AST scan**: parses `<file>` without executing it, walks top-level `ClassDef` nodes, and collects every
   class whose `bases` include `ModularPipelineBlocks`.
2. **Pick a class**: uses `--block_class_name` if given, else the first found. Errors with the list of available
   classes if your name doesn't match.
3. **Load and save**: imports the file via `importlib.util.spec_from_file_location` (this does execute the
   module — make sure your block.py is something you trust to run), instantiates the chosen class with no
   constructor args, and calls `.save_pretrained(os.getcwd())`.

The result is a Hub-uploadable directory laid out the way `ModularPipelineBlocks.from_pretrained` expects:
your block source, an `auto_map` in the config so consumers know to load it with `trust_remote_code=True`,
and any artifacts `save_pretrained` writes for that block class.

## End-to-end example

Given a `block.py` like:

```python
from diffusers.modular_pipelines import ModularPipelineBlocks, InputParam, OutputParam

class MyDenoiseBlock(ModularPipelineBlocks):
    model_name = "my-denoise"

    @property
    def inputs(self):
        return [
            InputParam("latents", type_hint="torch.Tensor", required=True, description="Noisy latents."),
            InputParam("guidance_scale", type_hint="float", default=7.5),
        ]

    @property
    def intermediate_outputs(self):
        return [OutputParam("latents", type_hint="torch.Tensor")]

    def __call__(self, components, state):
        # ... denoising logic ...
        return components, state
```

Package it:

```bash
diffusers-cli custom_blocks --block_module_name block.py
```

Output in cwd:

```
./
├── block.py
├── modular_config.json  # contains auto_map → MyDenoiseBlock
└── (any state files MyDenoiseBlock.save_pretrained writes)
```

Upload to the Hub:

```bash
hf upload my-user/my-denoise-block .
```

Consumers can now use it:

```python
from diffusers import ModularPipeline
pipe = ModularPipeline.from_pretrained("my-user/my-denoise-block", trust_remote_code=True)
```

Or via CLI:

```bash
diffusers-cli schema --model my-user/my-denoise-block --trust-remote-code
diffusers-cli run --model my-user/my-denoise-block --trust-remote-code \
    --pipeline-kwargs '{"latents": "...", "guidance_scale": 7.5}'
```

## Common errors

- **`Could not parse '<file>': SyntaxError`** — the file isn't valid Python. Fix the syntax; the AST step runs
  before any execution.
- **`block_class_name could not be retrieved. Available classes from <file>: [ClassA, ClassB]`** — your
  `--block_class_name` doesn't match any `ModularPipelineBlocks` subclass found. Pick from the list shown.
- **No classes found**: silent — the command will try to use the first entry in an empty list and raise
  `IndexError`. If you hit that, double-check your class actually inherits from `ModularPipelineBlocks`
  (the AST scan looks for that literal base-class name; aliased imports like `from diffusers import ...
  as MPB` won't be picked up).
- **Block requires constructor args**: the command calls `<ClassName>()` with no args. If your block needs
  `__init__` parameters, refactor to take them from `state`/`components` at `__call__` time instead, or
  hardcode defaults in `__init__`.

## Verifying the install

If `diffusers-cli` isn't on PATH after `pip install -e .`, reinstall with
`pip install -e . --force-reinstall --no-deps` and check `which diffusers-cli`. If the binary is missing recent
features (e.g. `unrecognized arguments: --lora`), reinstall. See the
[`diffusers-cli` skill](https://github.com/huggingface/diffusers/blob/main/.ai/skills/diffusers-cli/SKILL.md#verifying-the-cli-is-installed) for more.

## Related

- the [`diffusers-cli` docs](https://github.com/huggingface/diffusers/blob/main/docs/source/en/using-diffusers/cli.md) — once your block
  is uploaded, `schema` and `run` call it from the terminal without writing Python.
- diffusers' [modular pipelines docs](https://huggingface.co/docs/diffusers/main/en/modular_diffusers/overview) — for writing the block
  class itself.
````

## File: README.md
upstream: https://github.com/huggingface/diffusers/blob/main/README.md

````text
<!---
Copyright 2022 - The HuggingFace Team. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<p align="center">
    <br>
    <img src="https://raw.githubusercontent.com/huggingface/diffusers/main/docs/source/en/imgs/diffusers_library.jpg" width="400"/>
    <br>
<p>
<p align="center">
    <a href="https://github.com/huggingface/diffusers/blob/main/LICENSE"><img alt="GitHub" src="https://img.shields.io/github/license/huggingface/datasets.svg?color=blue"></a>
    <a href="https://github.com/huggingface/diffusers/releases"><img alt="GitHub release" src="https://img.shields.io/github/release/huggingface/diffusers.svg"></a>
    <a href="https://pepy.tech/project/diffusers"><img alt="GitHub release" src="https://static.pepy.tech/badge/diffusers/month"></a>
    <a href="CODE_OF_CONDUCT.md"><img alt="Contributor Covenant" src="https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg"></a>
    <a href="https://twitter.com/diffuserslib"><img alt="X account" src="https://img.shields.io/twitter/url/https/twitter.com/diffuserslib.svg?style=social&label=Follow%20%40diffuserslib"></a>
</p>

🤗 Diffusers is the go-to library for state-of-the-art pretrained diffusion models for generating images, audio, and even 3D structures of molecules. Whether you're looking for a simple inference solution or training your own diffusion models, 🤗 Diffusers is a modular toolbox that supports both. Our library is designed with a focus on [usability over performance](https://huggingface.co/docs/diffusers/conceptual/philosophy#usability-over-performance), [simple over easy](https://huggingface.co/docs/diffusers/conceptual/philosophy#simple-over-easy), and [customizability over abstractions](https://huggingface.co/docs/diffusers/conceptual/philosophy#tweakable-contributorfriendly-over-abstraction).

🤗 Diffusers offers three core components:

- State-of-the-art [diffusion pipelines](https://huggingface.co/docs/diffusers/api/pipelines/overview) that can be run in inference with just a few lines of code.
- Interchangeable noise [schedulers](https://huggingface.co/docs/diffusers/api/schedulers/overview) for different diffusion speeds and output quality.
- Pretrained [models](https://huggingface.co/docs/diffusers/api/models/overview) that can be used as building blocks, and combined with schedulers, for creating your own end-to-end diffusion systems.

## Installation

We recommend installing 🤗 Diffusers in a virtual environment from PyPI or Conda. For more details about installing [PyTorch](https://pytorch.org/get-started/locally/), please refer to their official documentation.

### PyTorch

With `pip` (official package):

```bash
pip install --upgrade diffusers[torch]
```

With `conda` (maintained by the community):

```sh
conda install -c conda-forge diffusers
```

### Apple Silicon (M1/M2) support

Please refer to the [How to use Stable Diffusion in Apple Silicon](https://huggingface.co/docs/diffusers/optimization/mps) guide.

## Quickstart

Generating outputs is super easy with 🤗 Diffusers. To generate an image from text, use the `from_pretrained` method to load any pretrained diffusion model (browse the [Hub](https://huggingface.co/models?library=diffusers&sort=downloads) for 30,000+ checkpoints):

```python
from diffusers import DiffusionPipeline
import torch

pipeline = DiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5", dtype=torch.float16)
pipeline.to("cuda")
pipeline("An image of a squirrel in Picasso style").images[0]
```

You can also dig into the models and schedulers toolbox to build your own diffusion system:

```python
from diffusers import DDPMScheduler, UNet2DModel
from PIL import Image
import torch

scheduler = DDPMScheduler.from_pretrained("google/ddpm-cat-256")
model = UNet2DModel.from_pretrained("google/ddpm-cat-256").to("cuda")
scheduler.set_timesteps(50)

sample_size = model.config.sample_size
noise = torch.randn((1, 3, sample_size, sample_size), device="cuda")
input = noise

for t in scheduler.timesteps:
    with torch.no_grad():
        noisy_residual = model(input, t).sample
        prev_noisy_sample = scheduler.step(noisy_residual, t, input).prev_sample
        input = prev_noisy_sample

image = (input / 2 + 0.5).clamp(0, 1)
image = image.cpu().permute(0, 2, 3, 1).numpy()[0]
image = Image.fromarray((image * 255).round().astype("uint8"))
image
```

Check out the [Quickstart](https://huggingface.co/docs/diffusers/quicktour) to launch your diffusion journey today!

## How to navigate the documentation

| **Documentation**                                                   | **What can I learn?**                                                                                                                                                                           |
|---------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Quickstart](https://huggingface.co/docs/diffusers/quicktour)                                                            | A basic crash course for loading pipelines, generating outputs, and applying common inference optimizations.  |
| [Loading](https://huggingface.co/docs/diffusers/using-diffusers/loading)                                                             | Guides for how to load and configure all the components (pipelines, models, and schedulers) of the library, as well as how to use different schedulers.                                         |
| [Modular Diffusers](https://huggingface.co/docs/diffusers/main/en/modular_diffusers/overview)                                             | Build flexible diffusion systems from modular pipeline components.               |
| [Optimization](https://huggingface.co/docs/diffusers/optimization/fp16)                                                        | Guides for how to optimize your diffusion model to run faster and consume less memory.                                                                                                          |
| [Training](https://huggingface.co/docs/diffusers/training/overview) | Guides for how to train a diffusion model for different tasks with different training techniques.                                                                                               |
## Contribution

We ❤️  contributions from the open-source community!
If you want to contribute to this library, please check out our [Contribution guide](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution).
If you are using an AI agent, please point it at the project conventions in [`.ai/`](https://github.com/huggingface/diffusers/tree/main/.ai) first (install them as a plugin with `claude plugin marketplace add huggingface/diffusers`, or a skill at a time with `diffusers-cli skills add <name>`) — see [Coding with AI agents](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution#coding-with-ai-agents).
You can look out for [issues](https://github.com/huggingface/diffusers/issues) you'd like to tackle to contribute to the library.
- See [Good first issues](https://github.com/huggingface/diffusers/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) for general opportunities to contribute
- See [New model/pipeline](https://github.com/huggingface/diffusers/issues?q=is%3Aopen+is%3Aissue+label%3A%22New+pipeline%2Fmodel
````
