Install & Compatibility
Where this runs
tested against v1.3.5 · 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
✓ 88.08s
py 3.11
✕ build_error
✓ 85.18s
py 3.12
✕ build_error
✓ 80.05s
py 3.13
✕ build_error
✓ 78.95s
py 3.9
✕ build_error
✕ build_error
5094MB installed
● package 5094MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cache_dit
✓ import cache_dit
DBCacheConfig
✓ from cache_dit import DBCacheConfig, ParallelismConfig, QuantizeConfig
ParallelismConfig
✓ from cache_dit import DBCacheConfig, ParallelismConfig, QuantizeConfig
QuantizeConfig
✓ from cache_dit import DBCacheConfig, ParallelismConfig, QuantizeConfig
enable_cache
✓ cache_dit.enable_cache(pipeline_instance)
To quickly get started, load a `DiffusionPipeline` model and apply `cache_dit.enable_cache()` to activate acceleration. You can customize caching, parallelism, and quantization through `DBCacheConfig`, `ParallelismConfig`, and `QuantizeConfig` respectively. The example demonstrates enabling hybrid acceleration with FP8 quantization and Ulysses parallelism.
import torch
from diffusers import DiffusionPipeline
import cache_dit
from cache_dit import DBCacheConfig, ParallelismConfig, QuantizeConfig
# Load a DiffusionPipeline model
pip = DiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5").to("cuda")
# Enable Cache-DiT acceleration with default cache, parallelism, and quantization
cache_dit.enable_cache(
pip,
cache_config=DBCacheConfig(), # Default cache settings
parallelism_config=ParallelismConfig(ulysses_size=2), # Example: enable Ulysses parallelism
quantize_config=QuantizeConfig(quant_type="float8_per_row") # Example: enable FP8 quantization
)
# Run inference as usual
prompt = "a photo of an astronaut riding a horse on mars"
image = pip(prompt).images[0]
image.save("astronaut_horse_mars.png")
# To disable cache_dit acceleration later:
# cache_dit.disable_cache(pip)
Debug
Known issues
gotchaAggressive caching settings can degrade output quality. Over-caching, particularly with high `residual_diff_threshold` or insufficient `Fn_compute_blocks`, can introduce artifacts or lower fidelity images.fixMonitor output quality and adjust `cache_config` parameters. Consider lowering `residual_diff_threshold` from the default (0.24) and increasing `Fn_compute_blocks` from the default (1) for better quality. Ensure sufficient inference steps are used.
affects: All versions
gotchaUsing `cache-dit` with `torch.compile` and dynamic input shapes may trigger `recompile_limit` errors, leading to fallback to eager mode and negating performance benefits.fixIncrease the `recompile_limit` for `torch._dynamo` if you encounter this issue. For example, `torch._dynamo.config.recompile_limit = 100`.
affects: All versions when using `torch.compile`
gotchaFP8 quantization with tensor parallelism may encounter memory layout mismatch errors in certain layers. The `per_tensor_fallback` option addresses this.fixSet `per_tensor_fallback=True` (which is often the default) in `QuantizeConfig` when calling `enable_cache` to allow unsupported layers to fall back to FP8 per-tensor quantization, preventing errors.
affects: All versions supporting FP8 quantization and tensor parallelism (v1.3.0+)
gotchaWhen integrating with ComfyUI, specific DiT models like LTX-2 or WAN2.2 14B MoE require dedicated optimizer nodes (e.g., `⚡ LTX2 Cache Optimizer`, `⚡ Wan Cache Optimizer`) instead of the general `⚡ CacheDiT Accelerator` node for optimal performance and quality.fixRefer to the `ComfyUI-CacheDiT` documentation and use the model-specific optimizer nodes for LTX-2 and WAN2.2 14B models.
affects: All versions when used with ComfyUI-CacheDiT
Upgrade
Version history
1.3.12latest on PyPI · released Jun 9, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
torchrequiredPyTorch-native inference engine, fundamental dependency.
diffusersrequiredBuilt on top of the Diffusers library, integrates with DiffusionPipeline.
setuptools-scmoptionalRequired for building SVDQuant from source.
nvccoptionalCUDA toolchain required for building CUDA extensions like SVDQuant from source.
para-attnoptionalRecommended for leveraging Context Parallelism features for distributed inference.