Installation

Diffusers requires Python 3.10+ and is tested with PyTorch 2.6+. Install PyTorch according to your system and setup.

Create a virtual environment for easier management of separate projects and to avoid compatibility issues between dependencies. Use uv, a Rust-based Python package and project manager, to create a virtual environment and install Diffusers.

uv venv my-env
source my-env/bin/activate

Install Diffusers with one of the following methods.

uv pip install diffusers["torch"] transformers

nvidia-smi

uv pip install torch --index-url https://pypi.nvidia.com
uv pip install diffusers

conda install -c conda-forge diffusers

uv pip install accelerate

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 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".

device = "cuda"  # or "mps", "xpu", "cpu"
pipeline.to(device)

To pick the device at runtime instead of hardcoding it, use torch.accelerator.

import torch

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

Editable install

An editable install is recommended for development workflows or if you’re using the main version of the source code. A special link is created between the cloned repository and the Python library paths. This avoids reinstalling a package after every change.

Clone the repository and install Diffusers with the following commands.

git clone https://github.com/huggingface/diffusers.git
cd diffusers
uv pip install -e ".[torch]"

You must keep the diffusers folder if you want to keep using the library with the editable install.

Update your cloned repository to the latest version of Diffusers with the command below.

cd ~/diffusers/
git pull

Cache

Model weights and files are downloaded from the Hub to a cache, which is usually your home directory. Change the cache location with the HF_HOME or HF_HUB_CACHE environment variables or configuring the cache_dir parameter in methods like from_pretrained().

export HF_HOME="/path/to/your/cache"
export HF_HUB_CACHE="/path/to/your/hub/cache"

from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    cache_dir="/path/to/your/cache"
)

Cached files allow you to use Diffusers offline. Set the HF_HUB_OFFLINE environment variable to 1 to prevent Diffusers from connecting to the internet.

export HF_HUB_OFFLINE=1

For more details about managing and cleaning the cache, take a look at the Understand caching guide.

Share files across repositories

The cache keeps one copy of a file even when several Hub repositories contain it. Many pipelines use the same text encoder, like T5. If a second pipeline’s repository has the same text encoder files as one you already downloaded, from_pretrained() uses the copy on disk instead of downloading it again. Diffusers requires huggingface_hub>=1.32.0, which turns file sharing on by default.

The cache matches files by their Xet hash, not by repository or model name. A sharded checkpoint is matched shard by shard, so the shards that match are shared even if the others differ.

A file is shared only when all of these are true:

• Both repositories store the file with Xet.
• Both downloads use the same cache directory, set by HF_HUB_CACHE or cache_dir.
• The filesystem supports symlinks.
• The files are byte-for-byte identical. Converting to a different dtype, saving in a different format, or resharding changes the hash.

Files you downloaded with an older version of huggingface_hub aren’t shared with new downloads. Only files downloaded with version 1.32.0 or later are added to the shared store.

File sharing saves download time and disk space, but not memory. To use one loaded model in several pipelines, see Reusing models in multiple pipelines.

To turn file sharing off, set HF_HUB_DISABLE_SHARED_BLOBS=1. Loading still works, and each repository keeps its own copy.

export HF_HUB_DISABLE_SHARED_BLOBS=1

Telemetry logging

Diffusers gathers telemetry information during from_pretrained() requests. The data gathered includes the Diffusers and PyTorch version, the requested model or pipeline class, and the path to a pretrained checkpoint if it is hosted on the Hub.

This usage data helps us debug issues and prioritize new features. Telemetry is only sent when loading models and pipelines from the Hub, and it is not collected if you’re loading local files.

Opt-out and disable telemetry collection with the HF_HUB_DISABLE_TELEMETRY environment variable.

export HF_HUB_DISABLE_TELEMETRY=1

set HF_HUB_DISABLE_TELEMETRY=1