diff --git a/docs/source/en/index.md b/docs/source/en/index.md index 0aca1d22c142..1d4aa166bec8 100644 --- a/docs/source/en/index.md +++ b/docs/source/en/index.md @@ -18,18 +18,28 @@ specific language governing permissions and limitations under the License. # Diffusers -Diffusers is a library of state-of-the-art pretrained diffusion models for generating videos, images, and audio. +Diffusers provides pretrained diffusion models and the building blocks for custom image, video, and audio workflows. -The library revolves around the [`DiffusionPipeline`], an API designed for: +It has two main paths. -- easy inference with only a few lines of code -- flexibility to mix-and-match pipeline components (models, schedulers) -- loading and using adapters like LoRA +- [`DiffusionPipeline`] supports few-line inference with pretrained checkpoints, plus adapters like LoRA. This is the easy path for generation. +- [Modular Diffusers](./modular_diffusers/overview) enables composable blocks and [`ModularPipeline`] for custom pipelines when you need more control. -Diffusers also comes with optimizations - such as offloading and quantization - to ensure even the largest models are accessible on memory-constrained devices. If memory is not an issue, Diffusers supports torch.compile to boost inference speed. +Optimizations such as offloading and quantization keep large models runnable on memory-constrained devices. If memory is not an issue, Diffusers also supports `torch.compile` for faster inference. -Get started right away with a Diffusers model on the [Hub](https://huggingface.co/models?library=diffusers&sort=trending) today! +Browse trending Diffusers models on the [Hub](https://huggingface.co/models?library=diffusers&sort=trending) now. ## Learn -If you're a beginner, we recommend starting with the [Hugging Face Diffusion Models Course](https://huggingface.co/learn/diffusion-course/unit0/1). You'll learn the theory behind diffusion models, and learn how to use the Diffusers library to generate images, fine-tune your own models, and more. +If you're a beginner, start with the [Hugging Face Diffusion Models Course](https://huggingface.co/learn/diffusion-course/unit0/1). It covers diffusion theory and how to generate images, fine-tune models, and more with Diffusers. + +The [Quickstart](./quicktour) also includes a copyable agent setup prompt for inference. + +## Where next + +- [Inference](./using-diffusers/loading) — load pipelines and run generation +- [Optimize and scale](./stable_diffusion) — memory, speed, quantization, and serving +- [Modular Diffusers](./modular_diffusers/overview) — build custom pipelines from blocks +- [Train and fine-tune](./training/overview) — train diffusion models and adapters +- [CLI](./using-diffusers/cli) - run and package pipelines from the command line + \ No newline at end of file diff --git a/docs/source/en/installation.md b/docs/source/en/installation.md index c4eb0e0f0d76..48a3581e0c06 100644 --- a/docs/source/en/installation.md +++ b/docs/source/en/installation.md @@ -12,7 +12,7 @@ specific language governing permissions and limitations under the License. # Installation -Diffusers is tested on Python 3.8+ and PyTorch 2.6+. Install [PyTorch](https://pytorch.org/get-started/locally/) according to your system and setup. +Diffusers requires Python 3.10+ and is tested with PyTorch 2.6+. Install [PyTorch](https://pytorch.org/get-started/locally/) according to your system and setup. Create a [virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) for easier management of separate projects and to avoid compatibility issues between dependencies. Use [uv](https://docs.astral.sh/uv/), a Rust-based Python package and project manager, to create a virtual environment and install Diffusers. @@ -26,8 +26,6 @@ Install Diffusers with one of the following methods. -PyTorch only supports Python 3.8 - 3.11 on Windows. - ```bash uv pip install diffusers["torch"] transformers ``` @@ -77,6 +75,8 @@ uv pip install git+https://github.com/huggingface/diffusers +Install with extras when you need them. `diffusers["torch"]` pulls PyTorch and Accelerate. Other extras cover quantization backends, training, and docs. See [`setup.py`](https://github.com/huggingface/diffusers/blob/main/setup.py) for the full list. + ## Devices Diffusers runs on any accelerator supported by PyTorch. The examples throughout the docs use `"cuda"` because it is the most common setup, but nothing is CUDA-specific. Swap in the device string for your hardware, such as `"xpu"` for Intel GPUs, `"mps"` for Apple silicon, or `"cpu"`. diff --git a/docs/source/en/quicktour.md b/docs/source/en/quicktour.md index 92f1d95001ed..831707fbc5a3 100644 --- a/docs/source/en/quicktour.md +++ b/docs/source/en/quicktour.md @@ -14,34 +14,36 @@ specific language governing permissions and limitations under the License. Diffusers is a library for developers and researchers that provides an easy inference API for generating images, videos and audio, as well as the building blocks for implementing new workflows. -Diffusers provides many optimizations out-of-the-box that makes it possible to load and run large models on setups with limited memory or to accelerate inference. +Diffusers provides many optimizations out-of-the-box that make it possible to load and run large models on setups with limited memory or to accelerate inference. This Quickstart will give you an overview of Diffusers and get you up and generating quickly. > [!TIP] -> Before you begin, make sure you have a Hugging Face [account](https://huggingface.co/join) in order to use gated models like [Flux](https://huggingface.co/black-forest-labs/FLUX.1-dev). +> Before you begin, make sure you have a Hugging Face [account](https://huggingface.co/join) to use gated models like [Flux](https://huggingface.co/black-forest-labs/FLUX.1-dev). Building a custom pipeline instead? See the [Modular Diffusers quickstart](./modular_diffusers/quickstart) and [overview](./modular_diffusers/overview). Follow the [Installation](./installation) guide to install Diffusers if it's not already installed. -## DiffusionPipeline +## Agent prompt -A diffusion model combines multiple components to generate outputs in any modality based on an input, such as a text description, image or both. +Paste this into your coding agent to get Diffusers set up for inference. -For a standard text-to-image model: +```text +Help me get set up with Hugging Face Diffusers for inference. -1. A text encoder turns a prompt into embeddings that guide the denoising process. Some models have more than one text encoder. -2. A scheduler contains the algorithmic specifics for gradually denoising initial random noise into clean outputs. Different schedulers affect generation speed and quality. -3. A UNet or diffusion transformer (DiT) is the workhorse of a diffusion model. +1. Install Diffusers for my environment with `uv pip install "diffusers[torch]"`. +2. If I need gated Hub models, help me authenticate to the Hugging Face Hub. +3. Install Diffusers coding agent skills with `diffusers-cli skills add diffusers-cli`. Pass `--cursor`, `--claude`, or `--codex` if auto-detect fails. Optionally pass `--all` to install every skill in the registry. +4. Run a first text-to-image with DiffusionPipeline or `diffusers-cli run`, using a small or current Quickstart model and the right `device_map` for my machine. +5. Ask what I want next and point me at the matching docs. +``` - At each step, it performs the denoising predictions, such as how much noise to remove or the general direction in which to steer the noise to generate better quality outputs. +## DiffusionPipeline - The UNet or DiT repeats this loop for a set amount of steps to generate the final output. - -4. A variational autoencoder (VAE) encodes and decodes pixels to a spatially compressed latent-space. *Latents* are compressed representations of an image and are more efficient to work with. The UNet or DiT operates on latents, and the clean latents at the end are decoded back into images. +[`DiffusionPipeline`] packages the pieces of a diffusion model (text encoder, scheduler, UNet or DiT, and VAE) into one class for inference. Load with [`~DiffusionPipeline.from_pretrained`], then call the pipeline. -The [`DiffusionPipeline`] packages all these components into a single class for inference. There are several arguments in [`~DiffusionPipeline.__call__`] you can change, such as `num_inference_steps`, that affect the diffusion process. Try different values and arguments to see how they change generation quality or speed. +Arguments on [`~DiffusionPipeline.__call__`] such as `num_inference_steps` change quality and speed. For loading details and mix-and-match components, see [Load pipelines](./using-diffusers/loading). To swap the scheduler, see [Schedulers](./using-diffusers/schedulers). -Load a model with [`~DiffusionPipeline.from_pretrained`] and describe what you'd like to generate. The example below uses the default argument values. +The examples below use the default argument values. @@ -71,7 +73,6 @@ Use `.frames[0]` to access the generated video output and [`~utils.export_to_vid ```py import torch from diffusers import AutoencoderKLWan, DiffusionPipeline -from diffusers.quantizers import PipelineQuantizationConfig from diffusers.utils import export_to_video vae = AutoencoderKLWan.from_pretrained( @@ -81,7 +82,7 @@ vae = AutoencoderKLWan.from_pretrained( ) pipeline = DiffusionPipeline.from_pretrained( "Wan-AI/Wan2.2-T2V-A14B-Diffusers", - vae=vae + vae=vae, dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu" ) @@ -101,9 +102,7 @@ export_to_video(video, "output.mp4", fps=16) ## LoRA -Adapters insert a small number of trainable parameters to the original base model. Only the inserted parameters are fine-tuned while the rest of the model weights remain frozen. This makes it fast and cheap to fine-tune a model on a new style. Among adapters, [LoRAs](./tutorials/using_peft_for_inference) are the most popular. - -Add a LoRA to a pipeline with the [`~loaders.QwenImageLoraLoaderMixin.load_lora_weights`] method. Some LoRAs require a special word to trigger them, such as `Realism`, in the example below. Check a LoRA's model card to see if it requires a trigger word. +[LoRA](./tutorials/using_peft_for_inference) adapters add a small style or subject checkpoint on top of a base pipeline. Load one with [`~loaders.QwenImageLoraLoaderMixin.load_lora_weights`]. Some LoRAs need a trigger phrase. Check the LoRA's model card. ```py import torch @@ -113,25 +112,21 @@ pipeline = DiffusionPipeline.from_pretrained( "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu" ) pipeline.load_lora_weights( - "flymy-ai/qwen-image-realism-lora", + "threecrowco/VolkClipartQwen", + weight_name="pytorch_lora_weights.safetensors", ) prompt = """ -super Realism cinematic film still of a cat sipping a margarita in a pool in Palm Springs in the style of umempart, California -highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain +Volk clipart style drawing of a cat sipping a margarita in a pool in Palm Springs, California, flat colors, bold outlines, simple shapes """ pipeline(prompt).images[0] ``` -Check out the [LoRA](./tutorials/using_peft_for_inference) docs or Adapters section to learn more. +## Quantization and optimizations -## Quantization +Large models often need less memory or more speed. Use [quantization](./quantization/overview) to shrink weights in memory, and [`~ModelMixin.compile_repeated_blocks`] to speed up later generates. For [model offloading](./optimization/memory#model-offloading) and other options, see [Optimize and scale](./stable_diffusion). -[Quantization](./quantization/overview) stores data in fewer bits to reduce memory usage. It may also speed up inference because it takes less time to perform calculations with fewer bits. - -Diffusers provides several quantization backends and picking one depends on your use case. For example, [bitsandbytes](./quantization/bitsandbytes) and [torchao](./quantization/torchao) are both simple and easy to use for inference, but torchao supports more [quantization types](./quantization/torchao#supported-quantization-types) like fp8. - -Configure [`PipelineQuantizationConfig`] with the backend to use, the specific arguments (refer to the [API](./api/quantization) reference for available arguments) for that backend, and which components to quantize. The example below quantizes the model to 4-bits and only uses 14.93GB of memory. +To use less memory, load in 4-bit with bitsandbytes. ```py import torch @@ -155,61 +150,9 @@ cinematic film still of a cat sipping a margarita in a pool in Palm Springs, Cal highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain """ pipeline(prompt).images[0] -print(f"Max memory reserved: {torch.cuda.max_memory_allocated() / 1024**3:.2f} GB") ``` -Take a look at the [Quantization](./quantization/overview) section for more details. - -## Optimizations - -> [!TIP] -> Optimization is dependent on hardware specs such as memory. Use this [Space](https://huggingface.co/spaces/diffusers/optimized-diffusers-code) to generate code examples that include all of Diffusers' available memory and speed optimization techniques for any model you're using. - -Modern diffusion models are very large and have billions of parameters. The iterative denoising process is also computationally intensive and slow. Diffusers provides techniques for reducing memory usage and boosting inference speed. These techniques can be combined with quantization to optimize for both memory usage and inference speed. - -### Memory usage - -The text encoders and UNet or DiT can use up as much as ~30GB of memory, exceeding the amount available on many free-tier or consumer GPUs. - -Offloading stores weights that aren't currently used on the CPU and only moves them to the GPU when they're needed. There are a few offloading types and the example below uses [model offloading](./optimization/memory#model-offloading). This moves an entire model, like a text encoder or transformer, to the CPU when it isn't actively being used. - -Call [`~DiffusionPipeline.enable_model_cpu_offload`] to activate it. By combining quantization and offloading, the following example only requires ~12.54GB of memory. - -```py -import torch -from diffusers import DiffusionPipeline -from diffusers.quantizers import PipelineQuantizationConfig - -quant_config = PipelineQuantizationConfig( - quant_backend="bitsandbytes_4bit", - quant_kwargs={"load_in_4bit": True, "bnb_4bit_quant_type": "nf4", "bnb_4bit_compute_dtype": torch.bfloat16}, - components_to_quantize=["transformer", "text_encoder"], -) -pipeline = DiffusionPipeline.from_pretrained( - "Qwen/Qwen-Image", - dtype=torch.bfloat16, - quantization_config=quant_config, - device_map="cuda" # or "mps", "xpu", "cpu" -) -pipeline.enable_model_cpu_offload() - -prompt = """ -cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California -highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain -""" -pipeline(prompt).images[0] -print(f"Max memory reserved: {torch.cuda.max_memory_allocated() / 1024**3:.2f} GB") -``` - -Refer to the [Reduce memory usage](./optimization/memory) docs to learn more about other memory reducing techniques. - -### Inference speed - -The denoising loop performs a lot of computations and can be slow. Methods like [torch.compile](./optimization/fp16#torchcompile) increases inference speed by compiling the computations into an optimized kernel. Compilation is slow for the first generation but successive generations should be much faster. - -The example below uses [regional compilation](./optimization/fp16#regional-compilation) to only compile small regions of a model. It reduces cold-start latency while also providing a runtime speed up. - -Call [`~ModelMixin.compile_repeated_blocks`] on the model to activate it. +To speed up later runs, compile repeated blocks on the transformer. The first generate after compile is a cold start and is slow. Later generates are faster. ```py import torch @@ -218,10 +161,8 @@ from diffusers import DiffusionPipeline pipeline = DiffusionPipeline.from_pretrained( "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu" ) +pipeline.transformer.compile_repeated_blocks(fullgraph=True) -pipeline.transformer.compile_repeated_blocks( - fullgraph=True, -) prompt = """ cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain @@ -229,4 +170,10 @@ highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous pipeline(prompt).images[0] ``` -Check out the [Accelerate inference](./optimization/fp16) or [Caching](./optimization/cache) docs for more methods that speed up inference. \ No newline at end of file +## Next steps + +- [Inference](./using-diffusers/loading) — pipelines, prompting, and adapters +- [Optimize and scale](./stable_diffusion) — memory, speed, quantization, and serving +- [Modular Diffusers](./modular_diffusers/overview) — composable blocks and custom pipelines +- [Train and fine-tune](./training/overview) — training scripts and adapters +- [CLI](./using-diffusers/cli) — generate from the command line diff --git a/docs/source/en/using-diffusers/cli.md b/docs/source/en/using-diffusers/cli.md index 02be2bd2fd0e..4ba3787f9272 100644 --- a/docs/source/en/using-diffusers/cli.md +++ b/docs/source/en/using-diffusers/cli.md @@ -12,7 +12,7 @@ specific language governing permissions and limitations under the License. # Command line interface -`diffusers-cli` is a command line client for running, inspecting, and packaging Diffusers pipelines. +`diffusers-cli` is a command line client for running, inspecting, and packaging Diffusers pipelines. ## Available commands @@ -26,35 +26,31 @@ specific language governing permissions and limitations under the License. | [`skills`](#skills) | Install pre-authored skill bundles into your AI coding agent. | > [!TIP] -> This page does not provide details for all options under each subcommand. For the full, always-current list of options for any subcommand, run `diffusers-cli --help` (`diffusers-cli run --help`). +> This page does not provide details for all options under each subcommand. For the full, always current list of options for any subcommand, run `diffusers-cli --help` (`diffusers-cli run --help`). -## `env` +## env -Prints Python/PyTorch/Diffusers versions, CUDA info, and installed optional deps. Use it when opening an +Prints Python, PyTorch, Diffusers versions, CUDA info, and installed optional deps. Use it when opening an issue so maintainers can reproduce your setup. ```bash diffusers-cli env ``` -## `schema` +## schema -Returns the pipeline's accepted inputs without downloading weights. This is useful when building `--pipeline-kwargs` +Returns the pipeline's accepted inputs without downloading weights. Use it when building `--pipeline-kwargs` for [`run`](#run). -Only the index file is fetched. Standard pipelines read `model_index.json`; modular pipelines read -`modular_model_index.json`; custom-block repos read `modular_config.json` and need `--trust-remote-code` since -loading them runs code from the Hub. +Only the index file is fetched. Standard pipelines read `model_index.json`. Modular pipelines read `modular_model_index.json`. Custom-block repos read `modular_config.json` and need `--trust-remote-code`, because loading them runs Hub code. ```bash diffusers-cli --format json schema --model black-forest-labs/FLUX.1-dev diffusers-cli schema --model my-org/my-custom-blocks --trust-remote-code ``` -## `run` +## run -Run a pipeline end-to-end. Auto-detects standard vs modular repos, auto-loads media inputs from URLs or local -paths, saves outputs by detecting the pipeline's return type, and can run remotely on a Hugging Face -Sandbox via `--remote`. +Run a pipeline end-to-end. The CLI auto-detects standard vs modular repos. It auto-loads media inputs from URLs or local paths, saves outputs from the pipeline's return type, and can run remotely on a Hugging Face Sandbox via `--remote`. Minimal example: @@ -82,7 +78,7 @@ diffusers-cli run \ ``` Both media keys and text keys accept a JSON array to run a batch through a single pipeline call. Each entry -in a media list is loaded individually (URL, local path, or bucket-mount path), and diffusers processes the +in a media list is loaded individually (URL, local path, or bucket-mount path), and Diffusers processes the whole list in one forward pass on the GPU: ```bash @@ -105,14 +101,14 @@ Configure how the CLI loads model weights and custom pipeline code. - `--dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32}` — weight dtype. - `--device-map ` — component placement. Accepts a torch device string (`cuda`, `cuda:0`, `cpu`, `mps`), `balanced` (auto-splits components across visible GPUs), or a JSON dict for explicit per-component placement. - Auto-detected if omitted. See [device_map](../training/distributed_inference#devicemap) for more details + Auto-detected if omitted. See [device_map](../training/distributed_inference#devicemap) for more details. - `--variant fp16` — pick a weight variant. - `--revision ` — pin a specific model revision. - `--trust-remote-code` — allow custom code from the Hub (required for repos that ship custom pipeline classes or modular blocks). See [Community pipelines](../using-diffusers/custom_pipeline_overview) for standard custom pipelines and [Modular Diffusers](../modular_diffusers/overview). -- `--lora ` — attach a LoRA adapter after loading. Each value is a JSON dict; repeat the flag to - stack multiple adapters. `lora_id` is required per entry; `lora_scale` defaults to `1.0`; +- `--lora ` — attach a LoRA adapter after loading. Each value is a JSON dict. Repeat the flag to + stack multiple adapters. `lora_id` is required per entry, `lora_scale` defaults to `1.0`, and `adapter_name` is optional (auto-generated as `lora_` when stacking). - Single: `--lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'` - Multiple: `--lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.6, "adapter_name": "koda"}' --lora '{"lora_id": "Shakker-Labs/FLUX.1-dev-LoRA-AntiBlur", "lora_scale": 0.4}'` @@ -123,27 +119,22 @@ Configure how the CLI loads model weights and custom pipeline code. ### Optimizations -- `--cpu-offload {model, group, auto}` — `model` calls `enable_model_cpu_offload`; `group` calls - `enable_group_offload(offload_type="leaf_level", use_stream=True)`. Onload target comes from `--device-map` - (which must be a plain device string for offload). See - [Model offloading](../optimization/memory#model-offloading) and - [Group offloading](../optimization/memory#group-offloading). Modular pipelines support only `auto`, which - offloads through their [`ComponentsManager`](../modular_diffusers/components_manager); the standard modes - raise for them, and `auto` raises for standard pipelines. +- `--cpu-offload {model, group, auto}` — onload target comes from `--device-map` (plain device string required for offload). + - `model` — `enable_model_cpu_offload` for standard pipelines. See [Model offloading](../optimization/memory#model-offloading). + - `group` — `enable_group_offload(offload_type="leaf_level", use_stream=True)` for standard pipelines. See [Group offloading](../optimization/memory#group-offloading). + - `auto` — modular only with [`ComponentsManager`](../modular_diffusers/components_manager). Standard modes raise on modular pipelines. `auto` raises on standard pipelines. - `--offload-margin ` — device memory kept free for activations under `--cpu-offload auto`, passed to `enable_auto_cpu_offload` as `memory_reserve_margin` (default `3GB`). Raise it when a large canvas runs out - of memory mid-forward: the offloader keeps components resident while they fit, so on a high-VRAM card the + of memory mid-forward. The offloader keeps components resident while they fit, so on a high-VRAM card the default margin can leave too little room for the activations of a long video. -- `--attention-backend {default, flash_hub, flash_varlen_hub, flash_4_hub, sage_hub}` — Hub-hosted attention - kernels, auto-downloaded on first use. Transformer-based pipelines only; ignored with a warning on legacy UNet - pipelines. See [Attention backends](../optimization/attention_backends). +- `--attention-backend` — Hub-hosted attention kernels, auto-downloaded on first use. Choices are `default` plus the Hub backends registered in Diffusers (for example `flash_hub`, `flash_varlen_hub`, `flash_4_hub`, `sage_hub`). Run `diffusers-cli run --help` for the current list. It only supports Transformer-based pipelines only, and is ignored with a warning on legacy UNet pipelines. See [Attention backends](../optimization/attention_backends). - `--vae-tiling` / `--vae-slicing` — lower VAE decode VRAM. See [VAE tiling](../optimization/memory#vae-tiling) and [VAE slicing](../optimization/memory#vae-slicing). - `--compile [JSON]` — compile denoiser modules with [torch.compile](../optimization/fp16#torchcompile). The CLI prefers [regional compilation](../optimization/fp16#regional-compilation) for modules with repeated blocks. Bare `--compile` uses `fullgraph=true`. A JSON object is forwarded to `torch.compile`. Not supported with `--context-parallel`. -- `--context-parallel` — Ulysses-style context parallelism on a DiT-based pipeline. Locally requires torchrun; +- `--context-parallel` — Ulysses-style context parallelism on a DiT-based pipeline. Locally requires torchrun, but under `--remote` the CLI wraps `torchrun --nproc-per-node=gpu` for you. See [Context parallelism](../training/distributed_inference#context-parallelism). @@ -153,7 +144,7 @@ Configure how the CLI loads model weights and custom pipeline code. `modular_model_index.json`, or because its `model_index.json` names a `ModularPipeline` subclass — so no flag is needed to opt in. -Some modular repos define several **workflows**: named tasks that share components but differ in which blocks +Some modular repos define several *workflows* like named tasks that share components but differ in which blocks run and which inputs they take. [MiniMax-H3](../api/pipelines/minimax_h3), for example, offers `t2va` (text to video and audio), `fl2va` (first and/or last keyframe) and `ref2va` (an ordered mix of image, video and audio references). Pass `--workflow` to select one: @@ -180,7 +171,7 @@ pipeline pick per call from the inputs it is given. diffusers-cli --format json schema --model MiniMaxAI/MiniMax-H3 --trust-remote-code ``` -`--workflow` applies to modular pipelines only; it is ignored with a warning on standard pipelines. +`--workflow` applies to modular pipelines only. It is ignored with a warning on standard pipelines. A modular pipeline returns a [`PipelineState`](../modular_diffusers/modular_pipeline) rather than a single output object, so `--output-key` names the intermediate to save. @@ -209,10 +200,14 @@ Directory outputs always use bare padded names (`0000`, `0001`, …). Explicit f stem and get the padded index appended when the batch produces multiple outputs. Use `--push-to` to upload outputs to a -[Hugging Face storage bucket](https://huggingface.co/docs/hub/en/storage-buckets). Accepts an HF bucket -id (`/`), an `hf://buckets//[/]` -[HF URI](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_uris), or a browser URL -for the same — a subpath is used as a folder prefix. The bucket is created if missing; objects land under +[Hugging Face storage bucket](https://huggingface.co/docs/hub/en/storage-buckets). It accepts an: + +- HF bucket id (`/`) +- `hf://buckets//[/]` +[HF URI](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_uris) +- browser URL + +A subpath is used as a folder prefix. The bucket is created if missing, and objects land under `[/]/`. ```bash @@ -236,14 +231,13 @@ not suppress local file creation. | yes | no | bucket only, no local download | | yes | yes | bucket AND `--output` | -`--format` shapes the stdout metadata (paths, timing, sandbox info) — it does not change the file format of +`--format` shapes the stdout metadata (paths, timing, sandbox info). It does not change the file format of the media itself. Written images are always PNG, videos MP4, audio WAV. ### Remote execution (`--remote`) -Run the same call inside a [Hugging Face Sandbox](https://huggingface.co/docs/huggingface_hub/en/guides/sandbox) -— an isolated cloud VM the CLI drives over HTTP: it uploads inputs, installs deps, runs the pipeline, downloads -outputs, then terminates the sandbox. Requires `huggingface_hub>=1.23`. +Run the same call inside a [Hugging Face Sandbox](https://huggingface.co/docs/huggingface_hub/en/guides/sandbox), an isolated cloud VM the CLI drives over HTTP. It uploads inputs, installs deps, runs the pipeline, downloads +outputs, then terminates the sandbox. Requires a current `huggingface_hub` with Sandbox support (Diffusers depends on `huggingface-hub>=1.31`). ```bash diffusers-cli run \ @@ -254,7 +248,7 @@ diffusers-cli run \ Remote flags: -- `--flavor ` — sandbox hardware (e.g. `a10g-small`, `h200`, `rtx-pro-6000`). +- `--flavor ` — sandbox hardware (for example, `a10g-small`, `h200`, `rtx-pro-6000`). - `--timeout ` — max wallclock for the run command inside the sandbox (default `10m`). - `--dependencies ` — extra pip deps (repeatable). Useful for pinning a diffusers branch tarball or adding pipeline-specific extras. @@ -262,17 +256,17 @@ Remote flags: - `--image ` — override the sandbox image. Must ship torch + CUDA compatible with your `--flavor`'s driver. - `--volume [:]` — mount an [HF storage bucket](https://huggingface.co/docs/hub/en/storage-buckets) - into the sandbox as a read-write directory. Repeatable. Default mount path is + into the sandbox as a read-write directory (repeatable). Default mount path is `/mnt/buckets/`. Reference mounted files from `--pipeline-kwargs` like any other local path. - Applied only on new sandbox creation — ignored when reconnecting via `--sandbox-id`. + Applied only on new sandbox creation and ignored when reconnecting via `--sandbox-id`. By default each `--remote` run is ephemeral (create → run → download → kill). To reuse a warm sandbox across runs — keeping deps, the model weight cache, and the `torch.compile` cache on its disk — keep it alive and reconnect: -- `--keep-alive` — don't terminate the sandbox after the run; its id is printed. +- `--keep-alive` — don't terminate the sandbox after the run. Its id is printed. - `--sandbox-id ` — reconnect to a kept-alive sandbox instead of creating a new one. -- `--idle-timeout ` — auto-shutdown after this much inactivity (default `10m`). Applied only on new sandbox creation — ignored when reconnecting via `--sandbox-id`. +- `--idle-timeout ` — auto-shutdown after this much inactivity (default `10m`). Applied only on new sandbox creation and ignored when reconnecting via `--sandbox-id`. ```bash # First run keeps the sandbox alive and prints sandbox_id=. @@ -301,7 +295,7 @@ diffusers-cli custom_blocks diffusers-cli custom_blocks --block_module_name my_block.py --block_class_name MyDenoiseBlock ``` -The block class must be instantiable with zero constructor args — hardcode defaults in `__init__` or read +The block class must be instantiable with zero constructor args and hardcodes defaults in `__init__` or read config from the pipeline `state` at call time. ## `fp16_safetensors` @@ -339,7 +333,5 @@ diffusers-cli skills add diffusers-cli --global diffusers-cli skills add --all --claude # or --codex / --cursor ``` -Without a target flag, the CLI installs for whichever agent launched it, or for every agent when it can't tell. -For Claude Code the skills are written as a plugin bundle at `.claude/skills/diffusers/`, so they are namespaced -as `/diffusers:`; Codex and Cursor get `.agents/skills//`. +Without a target flag, the CLI installs for the agent that launched it, or for every agent when it cannot tell. Claude Code gets a plugin bundle under `.claude/skills/diffusers/` (namespaced as `/diffusers:`). Codex and Cursor get `.agents/skills//`.