diffusion-pipe's own description is a warning about its cache

The repository description is a warning about stale cached tensors

The one-line summary on the repository is not a description of the project, it is a warning about it: delete the cache folder or use `regenerate_cache`, or you might get tensor shape errors from the old cached files. The same sentence appears again in the change log under the entry that removed attention masking from Flux 2, and a third time in a different form a couple of months later, where it says that if you are training Z-Image, Flux2 or Ernie-Image you must regenerate the cache because latent scaling now happens in the caching phase instead of inside the model. The reason is the pre-caching step: latents and text embeddings are computed ahead of time across multiple processes and GPUs so training does not pay for them every step. Those cached values are tensors derived from a specific scaling, and when the scaling moves, the old files do not become wrong-looking, they become the wrong shape. Nothing detects the mismatch, so the first symptom is an error deep in the model.

One dependency is pinned, and the same package appears twice

The requirements file has thirty entries and exactly one version constraint that closes anything: `deepspeed==0.18.4`. Everything else is a name or a floor, including `diffusers>=0.35.1`, and most are bare names with no lower bound at all. The page is explicit that this is deliberate, that most dependencies are intentionally left unpinned, and that you can update them with the upgrade flag on the same install command. Then there is the duplicate: `av` appears in the middle of the list and again at the very end as `av>=16.0.0`, after scipy. A package manager intersects the two, so the effective requirement is the stricter one, but the second line was clearly appended later without cleaning the first, and the same file also carries both `imageio[ffmpeg]` and `av` as video paths. The upshot for a training job that takes days is that `pip install -r requirements.txt` on two different days gives you two different stacks, and nothing in the repository records which one produced a checkpoint.

The tested PyTorch combination is from October 2025

PyTorch is deliberately absent from the requirements file, with the reason given: different GPUs sometimes need different versions of PyTorch or CUDA, so you may have to find a combination that works for your hardware. What the page then offers is one data point with a date on it: as of the time of writing, October 26 2025, PyTorch 2.9.0 with CUDA 12.8 works on a 4090 and is compatible with the then-current flash-attn 2.8.3. Flash Attention is also optional and also not in the requirements file, because some models need it. So the two most consequential installs in the whole setup are unpinned, and the documented good combination predates most of the models the same file now claims to support. The install order itself is careful, conda with Python 3.12, then torch, then nvcc matched to the CUDA version, then the requirements file, and the transformer engine for Cosmos needs include paths pointed at the cudnn headers in your own environment.

Submodules have to be updated by hand after every pull

The clone is spelled with a flag:

git clone --recurse-submodules https://github.com/tdrussell/diffusion-pipe

and the page covers the case where you forgot it, with `git submodule init` followed by `git submodule update`. The updating section is the part worth reading twice, because it is two commands and a warning:

git pull
git submodule update

The instruction is to make sure you run the submodule update in case a submodule has been updated to a new commit. The tree carries a `.gitmodules` file and a `submodules/` directory, and a lot of the value of this repository lives there, since adding a model means implementing a single subclass and the model implementations are the code that changes. A plain pull that leaves those behind gives you training code that expects a model signature the vendored copy does not have, and the resulting error points at the training script rather than at the pull you did ten minutes ago.

A missing caption file is a warning, and training carries on

The dataset contract is simple and forgiving in a way that will cost you a run. A dataset is one or more directories of image or video files plus matching captions, where the caption file is a `.txt` file with the same base name in the same directory, so `image1.png` pairs with `image1.txt`. If a media file has no matching caption, the behaviour is that a warning is printed and training proceeds with an empty caption. There is no error, no non-zero exit, and no count of how many were empty. On a caption-conditioned trainer that is the worst possible default, because a dataset where a fifth of the files silently got an empty caption trains the model to associate those images with nothing while looking like a successful run. You can mix images and videos in one directory, though the author suggests separating them in case you need per-directory settings.

Twenty-eight models on one line, several of them only partly supported

The supported models are a single comma-separated sentence listing about twenty-eight families, from SDXL and Flux through Qwen-Image, HunyuanImage, AuraFlow, Z-Image, Anima, Ideogram4, Krea 2 and MiniMax H3, and the change log shows a new one arriving every few weeks through 2026. The single line overstates what each entry means, because the change log is where the caveats live. Qwen-Image-2.1 is text-to-image training only. MiniMax H3 arrived as T2I and T2VA only, and its CFG-augmented training has to be enabled from the example TOML. Initial LTX 2.3 support is T2I and T2V only, and no audio. ComfyUI-based quantized weight training, which is what makes LoRA training on quantized models work, is said to apply to any ComfyUI-based model from Z-Image onwards with one exclusion, Anima, and is hedged with the words should theoretically. The page points to a supported models document for the per-model options and the LoRA format.

The example configs are named after VRAM budgets, and Windows means WSL 2

The guidance for hardware is unusually concrete, because the example directory holds configs named for it: a Qwen-Image config for a 24 GB card, a Wan 14B config for minimum VRAM, plus a main example that is described as the one with all the comments in it, and separate dataset configs per family. The launch line carries its own environment:

NCCL_P2P_DISABLE="1" NCCL_IB_DISABLE="1" deepspeed --num_gpus=1 train.py --deepspeed --config examples/hunyuan_video.toml

Those two variables are there for RTX 4000 series cards, which is the sort of detail that only exists because somebody lost a day to it. The platform story is blunter: native Windows will be difficult or impossible because DeepSpeed only has partial Windows support, DeepSpeed is a hard requirement since the whole training script is built around its pipeline parallelism, and the supported route is WSL 2, which is what the author recommends if you must use Windows. Two content loaders define what your data can be, since images are whatever Pillow opens and videos are whatever ImageIO opens, which is why multi-frame WebP video does not work.

Editorial conclusion

Use this if you are training a LoRA on a single 24 GB card and your model is on the supported list, because the pipeline parallelism and the pre-caching are the reason it exists, and the example configs are named for the hardware people actually have. Before a long run, delete the cache directory or pass the regenerate flag, and treat that as part of the command rather than a troubleshooting step. Then accept that your environment is not reproducible: one dependency is pinned, the rest are floor-only, the page even recommends upgrading all of them, and the tested PyTorch combination on file is from October 2025. If you need a run you can repeat in six months, capture the full resolved environment yourself. Two smaller things: work on WSL rather than native Windows, and read the per-model caveats, because several of the twenty-eight entries are text-to-image only.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. README
4. Releases