Install & Compatibility
Where this runs
tested against v0.1.1.post1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 95.55s
py 3.11
✕ build_error
✓ 88.15s
py 3.12
✕ build_error
✓ 80.7s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ timeout
5257MB installed
● package 5257MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sample_dpmpp_2m
✓ from k_diffusion import sampling
# ... sampling.sample_dpmpp_2m(...)
✗ from k_diffusion.sampling import sample_dpmpp_2m_sde_v2
Early versions might have used `sample_dpmpp_2m_sde_v2` or similar, but direct `sample_dpmpp_2m` is a common and stable choice. Always check the available samplers in `k_diffusion.sampling`.
CompVisDenoiser
✓ from k_diffusion import external
# ... external.CompVisDenoiser(...)
✗ from k_diffusion.models import CompVisDenoiser
`CompVisDenoiser` is part of the `external` module, designed to wrap models from other libraries like CompVis/Stable Diffusion.
This quickstart demonstrates how to set up a dummy UNet model, wrap it using `k_diffusion.external.CompVisDenoiser` to conform to the library's API, and perform a basic sampling step using `sample_dpmpp_2m`. In a real application, the `DummyUNet` would be replaced by your actual pre-trained model (e.g., a Stable Diffusion UNet).
import torch
from k_diffusion import sampling, external
# 1. Define a dummy UNet-like model (replace with your actual pre-trained UNet)
# This mock UNet simulates a model expecting (latent, timestep, conditioning) input.
class DummyUNet(torch.nn.Module):
def __init__(self, in_channels=4, out_channels=4, img_size=64):
super().__init__()
self.conv = torch.nn.Conv2d(in_channels, out_channels, kernel_size=3, padding=1)
self.relu = torch.nn.ReLU()
def forward(self, x, timesteps, context=None):
# In a real UNet, timesteps and context would be used for conditioning.
return self.relu(self.conv(x))
# Instantiate the dummy UNet
inner_model = DummyUNet()
# 2. Wrap the UNet with k-diffusion's external denoiser (e.g., for Stable Diffusion latents)
# This wrapper adapts the UNet's API to k-diffusion's expected (x, sigma) signature.
model_wrap = external.CompVisDenoiser(inner_model)
model_wrap.eval().cpu() # Set to eval mode and move to CPU for quickstart simplicity
# 3. Prepare initial noisy latents and define the sampling schedule
batch_size = 1
channels = 4 # Common for Stable Diffusion latent space
height, width = 64, 64 # Latent resolution (e.g., 512x512 image -> 64x64 latent)
initial_noise = torch.randn(batch_size, channels, height, width, device='cpu') * 8.0
sigmas = sampling.get_sigmas_karras(n=40, sigma_min=0.1, sigma_max=8.0, device='cpu')
# 4. Run the sampling process using a DPM++ 2M sampler
# The sampler takes the wrapped model, initial noise, and the sigma schedule.
with torch.no_grad():
print("Starting K-Diffusion sampling (DPM++ 2M)...")
denoised_latents = sampling.sample_dpmpp_2m(
model_wrap, # The wrapped model callable
initial_noise, # Initial noisy latents
sigmas # Sigma schedule
# Optional: `extra_args` can pass conditioning, e.g., {'cond': text_embeddings}
)
print(f"Sampling complete. Denoised latents shape: {denoised_latents.shape}")
# In a real pipeline, `denoised_latents` would then be decoded to an image.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'k_diffusion'
The k-diffusion library is not installed in your Python environment.
fixRun `pip install k-diffusion` to install the library.
TypeError: forward() got an unexpected keyword argument 'sigma'
Your underlying PyTorch model's `forward` method does not accept `sigma` as an argument directly, but a `k_diffusion` sampler is trying to pass it.
fixYou likely need to wrap your model using `k_diffusion.external.CompVisDenoiser` or a similar wrapper that adapts the `k-diffusion` API to your model's native `forward` signature.
RuntimeError: CUDA out of memory. Tried to allocate X GiB (GPU N; X GiB total capacity; Y GiB already allocated; Z GiB free; P MiB reserved in total by PyTorch)
Your GPU does not have enough memory to run the model or sampling process with the current settings.
fixReduce the `batch_size`, use a smaller image resolution, or offload parts of your model to CPU if the architecture allows (e.g., with specific `diffusers` pipelines). Consider using a GPU with more VRAM.
AttributeError: module 'k_diffusion.sampling' has no attribute 'sample_dpmpp_2m_sde_v2'
The specific sampler function name you are trying to use does not exist or has been renamed in your installed version of `k-diffusion`.
fixCheck the available functions in the `k_diffusion.sampling` module by using `dir(k_diffusion.sampling)` or consult the official GitHub repository for the correct sampler names for your version.
Upgrade
Version history
0.1.1.post1latest on PyPI · released Dec 7, 2023
Audit
Dependencies
torchrequiredCore deep learning framework
tqdmrequiredProgress bar for sampling
safetensorsrequiredFor loading and saving model weights securely