Guide · Open source

How to use denoising-diffusion-pytorch: install and train a diffusion model

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

denoising-diffusion-pytorch is an open-source Python library that implements Denoising Diffusion Probabilistic Models in PyTorch. Diffusion models learn to generate new data, such as images, by learning to reverse a process that gradually adds noise to training examples. This guide is for developers and learners who want to install the package, run the basic model code, and train a small generator on their own folder of images.

denoising-diffusion-pytorchlucidrains/denoising-diffusion-pytorch · ★ 10.7k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm Python and PyTorch are installed in the environment you will use.
2Install the package. Run pip install denoising_diffusion_pytorch to install it from PyPI.
3Build the model. Create a Unet and pass it to GaussianDiffusion with an image_size and timesteps.
4Test one training step. Pass a batch of images normalized from 0 to 1 to the diffusion object, then call loss.backward().
5Train on your folder. Use Trainer with the path to your image folder, then call trainer.train(). Results are logged to ./results.
6Sample new images. After training, call diffusion.sample with a batch_size to generate images.

What denoising-diffusion-pytorch is and who it is for

The library is a readable PyTorch reference implementation of the Denoising Diffusion Probabilistic Model paper. The README describes the method as using denoising score matching to estimate the gradient of the data distribution, followed by Langevin sampling to sample from the true distribution.

It suits researchers and engineers who want a clear PyTorch reference, developers training a small image generator on their own images, and people learning the method by reading and running code. The README only shows code usage, so it is not a click-to-use image generator.

Install denoising-diffusion-pytorch with pip

You need Python and PyTorch installed. The package is published on PyPI, so you install it with pip using the command from the README.

Prerequisites: Python and PyTorch
Package name on PyPI: denoising_diffusion_pytorch

pip install denoising_diffusion_pytorch

Build a model and run one training step

Start by creating a Unet, the denoising network, and wrapping it in GaussianDiffusion together with an image size and a number of timesteps. Passing a batch of images with values from 0 to 1 into the diffusion object returns a loss, which you can call backward on.

After training, diffusion.sample generates new images. The README example uses random tensors only to show the shapes, so you would replace them with real data.

Unet arguments in the example: dim, dim_mults and flash_attn
GaussianDiffusion arguments in the example: image_size and timesteps
Images should be normalized from 0 to 1

import torch
from denoising_diffusion_pytorch import Unet, GaussianDiffusion

model = Unet(
    dim = 64,
    dim_mults = (1, 2, 4, 8),
    flash_attn = True
)

diffusion = GaussianDiffusion(
    model,
    image_size = 128,
    timesteps = 1000    # number of steps
)

training_images = torch.rand(8, 3, 128, 128) # images are normalized from 0 to 1
loss = diffusion(training_images)
loss.backward()

# after a lot of training

sampled_images = diffusion.sample(batch_size = 4)
sampled_images.shape # (4, 3, 128, 128)

Train on a folder of your own images with Trainer

If you pass a folder name and the image dimensions, the Trainer class handles training. In the README example you give it the path to your images, a batch size, a learning rate, a number of training steps and options such as mixed precision and FID calculation.

Samples and model checkpoints are logged to ./results periodically. The example values, such as 700000 training steps, are illustrative settings from the README and will take a long time on ordinary hardware.

Replace 'path/to/your/images' with your own image folder
Set amp = True to turn on mixed precision
Set calculate_fid = True to calculate FID during training
Outputs go to ./results

from denoising_diffusion_pytorch import Unet, GaussianDiffusion, Trainer

model = Unet(
    dim = 64,
    dim_mults = (1, 2, 4, 8),
    flash_attn = True
)

diffusion = GaussianDiffusion(
    model,
    image_size = 128,
    timesteps = 1000,           # number of steps
    sampling_timesteps = 250    # number of sampling timesteps (using ddim for faster inference [see citation for ddim paper])
)

trainer = Trainer(
    diffusion,
    'path/to/your/images',
    train_batch_size = 32,
    train_lr = 8e-5,
    train_num_steps = 700000,         # total training steps
    gradient_accumulate_every = 2,    # gradient accumulation steps
    ema_decay = 0.995,                # exponential moving average decay
    amp = True,                       # turn on mixed precision
    calculate_fid = True              # whether to calculate fid during training
)

trainer.train()

Use multi-GPU training with Accelerate

The README says the Trainer class is equipped with Hugging Face Accelerator. You run the accelerate CLI from the project root, where your training script is. First configure it, then launch the script.

Run accelerate config once in the project directory
Then run accelerate launch train.py

$ accelerate config

$ accelerate launch train.py

Try the 1D sequence variant

The README includes a 1D Unet and Gaussian Diffusion implementation for sequence data. It uses Unet1D, GaussianDiffusion1D, Trainer1D and Dataset1D. The README notes that Trainer1D does not evaluate generated samples, so you would add your own metric if you need one, after an editable install with pip install -e .

import torch
from denoising_diffusion_pytorch import Unet1D, GaussianDiffusion1D, Trainer1D, Dataset1D

model = Unet1D(
    dim = 64,
    dim_mults = (1, 2, 4, 8),
    channels = 32
)

diffusion = GaussianDiffusion1D(
    model,
    seq_length = 128,
    timesteps = 1000,
    objective = 'pred_v'
)

training_seq = torch.rand(64, 32, 128) # features are normalized from 0 to 1

loss = diffusion(training_seq)
loss.backward()

dataset = Dataset1D(training_seq)

trainer = Trainer1D(
    diffusion,
    dataset = dataset,
    train_batch_size = 32,
    train_lr = 8e-5,
    train_num_steps = 700000,
    gradient_accumulate_every = 2,
    ema_decay = 0.995,
    amp = True,
)
trainer.train()

sampled_seq = diffusion.sample(batch_size = 4)
sampled_seq.shape # (4, 32, 128)

What people use it for

Learning how denoising diffusion works by running the README code step by step
Training a small image generator on a personal folder of images
Experimenting with the 1D Unet and GaussianDiffusion1D on sequence data
Comparing your own diffusion code against a readable PyTorch reference

Frequently asked questions

How do I install denoising-diffusion-pytorch?

Install it from PyPI with pip install denoising_diffusion_pytorch. The README lists Python and PyTorch as the prerequisites, so make sure both are available first.

Is denoising-diffusion-pytorch free to use?

The repository is listed under the MIT licence. Check the licence file in the repository for the full terms before using it in a project.

What do I need to run denoising-diffusion-pytorch?

The README names Python and PyTorch as prerequisites. Training image models also needs enough compute for the chosen image size and number of steps, which the README does not specify.

Does denoising-diffusion-pytorch come with pretrained models?

The README describes training code rather than released weights. You train the model on your own images using the Trainer class.

What are alternatives to denoising-diffusion-pytorch?

The README lists Hugging Face diffusers, OpenAI guided-diffusion and the annotated diffusion code from the Hugging Face blog as comparable projects. Pick based on whether you want a readable reference or a broader library.

Where do the training samples and checkpoints go?

According to the README, samples and model checkpoints are logged to ./results periodically during training. Check that folder if you do not see output.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use denoising-diffusion-pytorch if you are a developer or researcher who wants a readable PyTorch reference and is comfortable running Python code to train a small image or sequence model. If you need a ready-made image generator with a graphical interface, a supported production product, or released pretrained weights, the README does not describe those, so look at alternatives such as Hugging Face diffusers.

Install options & downloads