安装

Diffusers 需要 Python 3.10+，并已在 PyTorch 2.6+ 上进行测试。请根据您的系统和配置安装 PyTorch。

创建一个虚拟环境，以便更轻松地管理独立项目，并避免依赖项之间的兼容性问题。使用基于 Rust 的 Python 包和项目管理器 uv 来创建虚拟环境并安装 Diffusers。

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

使用以下任一方法安装 Diffusers。

pip

NVIDIA Spark (ARM64)

conda

source

在需要时安装附加组件。diffusers["torch"] 会拉取 PyTorch 和 Accelerate。其他附加组件涵盖量化后端、训练和文档。完整列表请参见 setup.py。

设备

Diffusers 支持 PyTorch 兼容的任何加速器。文档中的示例使用 "cuda"，因为这是最常见的配置，但没有任何 CUDA 专属内容。请根据硬件替换设备字符串，例如 Intel GPU 使用 "xpu"，Apple 芯片使用 "mps"，或 "cpu"。

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

要在运行时选择设备而不是硬编码，请使用 torch.accelerator。

import torch

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

在开发工作流中，或者当你使用源代码的 main 版本时，建议使用可编辑安装。这会在克隆的仓库和 Python 库路径之间创建一个特殊链接，从而避免每次修改后都需要重新安装包。

使用以下命令克隆仓库并安装 Diffusers。

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

如果您想继续使用可编辑安装方式使用该库，则必须保留 diffusers 文件夹。

使用以下命令将您克隆的仓库更新到 Diffusers 的最新版本。

cd ~/diffusers/
git pull

模型权重和文件会从 Hub 下载到缓存目录，通常位于您的主目录。您可以通过设置 HF_HOME 或 HF_HUB_CACHE 环境变量，或在 from_pretrained() 等方法中配置 cache_dir 参数来更改缓存位置。

环境变量

from_pretrained

缓存文件可让您离线使用 Diffusers。将 HF_HUB_OFFLINE 环境变量设置为 1，即可阻止 Diffusers 连接互联网。

export HF_HUB_OFFLINE=1

如需了解有关管理和清理缓存的更多详细信息，请参阅了解缓存指南。

Diffusers 会在 from_pretrained() 请求期间收集遥测信息。所收集的数据包括 Diffusers 和 PyTorch 的版本、请求的模型或 pipeline 类，以及如果预训练检查点托管在 Hub 上，则还包括其路径。

这些使用数据有助于我们调试问题并确定新功能的优先级。仅在从 Hub 加载模型和管道时才会发送遥测数据，如果您加载的是本地文件，则不会收集此类数据。

使用 HF_HUB_DISABLE_TELEMETRY 环境变量可退出并禁用遥测数据收集。

Linux/macOS

Windows