Diffusers 安装完全指南：pip、源码与可编辑安装，以及缓存与遥测配置

🤗 Diffusers 是一个用于在 PyTorch 中训练和推理图像、视频与音频扩散模型的现代库。本文基于仓库文档 docs/source/pt/installation.md 展开，系统梳理 Diffusers 的全部安装路径（虚拟环境 + pip、源码安装、可编辑安装）、模型缓存管理、离线使用与遥测隐私配置，并结合当前仓库的 setup.py 与 hub_utils.py 等源码给出可验证的实现细节。读完本文，你将能根据“日常使用 / 紧跟 main 分支 / 参与贡献开发”三种场景，正确选择并落地一套可复现的 Diffusers 环境。

一、环境要求：版本前提与依赖全景

文档开头明确了 Diffusers 的测试基线。需要注意，仓库文档存在版本演进：docs/source/pt/installation.md 写的是 "Python 3.8+ 与 PyTorch 1.7.0+"，而英文版 docs/source/en/installation.md 已更新为 "Python 3.8+ 与 PyTorch 2.6+"。从当前仓库的实际约束看，setup.py 中 python_requires=">=3.10.0"（setup.py）且核心依赖声明为 torch>=2.6（setup.py），因此当前仓库实际要求 Python 3.10+ 与 PyTorch 2.6+，葡萄牙语文档中的旧版本号属于翻译滞后，安装时请以英文文档与 setup.py 为准。

除了 PyTorch，仓库的核心运行依赖还包括（见 setup.py 的 install_requires）：

• huggingface-hub>=1.26.0,<2.0：负责模型下载、缓存与 Hub 交互；
• safetensors>=0.8.0：安全张量格式，加载权重的主路径；
• accelerate>=0.31.0：设备管理与并行推理基础设施；
• numpy、regex、requests、Pillow、filelock、importlib_metadata、httpx<1.0.0。

此外 setup.py 定义了 extras["torch"] = deps_list("torch", "accelerate")，这正是 pip install diffusers["torch"] 会拉取的内容。若需训练，可追加 training extra（含 datasets、tensorboard、peft 等，见 setup.py）。

二、pip 安装：面向日常使用的标准路径

2.1 创建并激活虚拟环境

官方推荐在虚拟环境中安装，以隔离不同项目的依赖、避免版本冲突。文档给出的命令为：

python -m venv .env
source .env/bin/activate

Windows 下激活命令为 .env\Scripts\activate。如果你偏好更快的包管理器，英文文档也提供了基于 uv 的等价流程：uv venv my-env && source my-env/bin/activate。

2.2 安装 Diffusers 与 Transformers

官方明确建议一并安装 🤗 Transformers，因为 Diffusers 的很多管线（尤其是 Stable Diffusion 系列）依赖其文本编码器（CLIP、T5 等）与分词器：

pip install diffusers["torch"] transformers

这里 ["torch"] 是 extras 语法，等价于 pip install diffusers torch accelerate，确保 PyTorch 与 Accelerate 一并就位。

安装完成后可通过 pip list | grep -i diffusers 验证版本；仓库当前开发版本号可在 setup.py 中看到为 0.41.0.dev0。安装成功后可执行以下最小冒烟测试：

python -c "from diffusers import __version__; print(__version__)"

三、源码安装：紧跟 main 分支的最新特性

如果你希望第一时间获得最新功能——例如某个 bug 已在 main 上修复但尚未发布正式版——可以从源码安装。它安装的是开发分支 main 而非稳定版 stable，因此功能最新，但稳定性没有保证。

源码安装前，文档要求先确保 Accelerate 就位：

pip install accelerate

然后从 GitHub 源码安装：

pip install git+https://github.com/huggingface/diffusers

该命令会拉取仓库最新 main 代码并构建安装。官方也坦诚地指出：main 分支并非永远稳定，团队会尽量保证其可用，大多数问题通常在数小时或一天内解决；若遇到问题，建议到仓库提交 Issue 以便尽快修复。

四、可编辑安装：面向开发与代码贡献

当你有以下两种需求时，应选择可编辑安装（editable install）：

• 日常使用 main 分支源码；
• 参与 Diffusers 开发，需要修改源码并即时验证效果。

执行方式为克隆仓库并安装：

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

可编辑安装的本质是：在克隆目录与 Python 库搜索路径之间建立特殊链接（见 docs/source/pt/installation.md 的说明），Python 解释器会优先在克隆目录中查找 diffusers 包。例如，若包通常安装于 ~/anaconda3/envs/main/lib/python3.10/site-packages/，可编辑安装后 Python 还会在 ~/diffusers/ 中查找，因此修改克隆目录中的代码无需重新安装即可生效。

需要注意两个使用要点：

1. 必须保留克隆的 diffusers 文件夹，删除后库将无法使用（文档以 [!WARNING] 明确警告）；
2. 更新代码只需同步 git：

cd ~/diffusers/
git pull

下次运行 Python 时即会加载最新的 main 版本代码。

五、模型缓存与离线使用

5.1 缓存位置与三种配置方式

调用 from_pretrained 从 Hub 下载的模型权重与配置文件会缓存在本地，默认位于用户主目录。官方文档提供了两种修改缓存位置的方式：

• 环境变量（优先级高，全局生效）：

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

• from_pretrained 的 cache_dir 参数（按次指定，仅对本次加载生效）：

from diffusers import DiffusionPipeline

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

从源码看，cache_dir 贯穿了加载链路：在 pipeline_utils.py 的 DiffusionPipeline.from_pretrained 中，cache_dir = kwargs.pop("cache_dir", None)（pipeline_utils.py）被取出后一路透传给底层模型与权重加载逻辑；而 constants.py 中 HF_MODULES_CACHE 则基于 HF_HOME 推导动态模块缓存目录，说明 HF_HOME 的调整会影响模块级缓存的落点。

5.2 离线运行

缓存使 Diffusers 可以完全离线运行。设置环境变量即可阻止所有网络访问：

export HF_HUB_OFFLINE=True

从实现看，huggingface_hub.constants 中的 HF_HUB_OFFLINE 会被 hub_utils.py 导入使用，同时仓库还以 HF_ENDPOINT 支持自定义 Hub 端点（constants.py），在受限网络环境（如内网镜像）下也值得关注。离线模式下，from_pretrained 只读取已缓存文件，未缓存的内容会直接报错，因此首次使用建议在线完成下载。

5.3 缓存管理

缓存目录内以 repo 为单位组织快照，长时间使用会积累大量旧版本文件。官方文档建议参考 huggingface_hub 的缓存管理指南（Understand caching）进行查看与清理——例如通过 huggingface-cli scan-cache 查看占用、huggingface-cli delete-cache 清理过期快照，这些命令属于 huggingface_hub 生态，适用于 Diffusers 生成的缓存。

六、遥测数据：收集内容与关闭方法

6.1 收集什么、何时收集

官方文档明确：库会在 DiffusionPipeline.from_pretrained 请求期间收集遥测信息，包括 Diffusers 与 PyTorch 版本、请求的模型或管线类、以及（若 checkpoint 托管在 Hub 上）其路径。这些数据用于调试问题与排定功能优先级。

从源码可以确认遥测的落地实现：hub_utils.py 中的 http_user_agent() 会构造形如 diffusers/<版本>; python/<版本>; session_id/<会话ID> 的 User-Agent，并在 PyTorch/ONNX Runtime 可用时附加其版本号。关键细节：遥测仅在从 Hub 加载模型与管线时随请求头发送；若加载本地文件，则不会触发收集。

6.2 关闭遥测

官方尊重隐私，提供了关闭开关。葡萄牙语文档给出的变量名为 DISABLE_TELEMETRY：

# Linux/macOS
export DISABLE_TELEMETRY=YES

# Windows
set DISABLE_TELEMETRY=YES

需要说明：英文文档与当前源码中使用的实际变量是 HF_HUB_DISABLE_TELEMETRY（hub_utils.py 直接导入自 huggingface_hub.constants），推荐按如下方式设置：

# Linux/macOS
export HF_HUB_DISABLE_TELEMETRY=1

# Windows
set HF_HUB_DISABLE_TELEMETRY=1

从源码逻辑看，当 HF_HUB_DISABLE_TELEMETRY 或 HF_HUB_OFFLINE 任一为真时，User-Agent 会附加 telemetry/off 标记（hub_utils.py），即离线模式下遥测同样自动关闭。DISABLE_TELEMETRY 属于早期版本变量，建议在兼容新旧文档的前提下两者都设置，或直接采用代码确认的 HF_HUB_DISABLE_TELEMETRY。

七、安装后验证与排障要点

安装完成后，建议按以下顺序做一次完整自检：

# 1. 版本确认
python -c "from diffusers import __version__; print(__version__)"

# 2. 检查 PyTorch 与设备可用性
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

# 3. 从 Hub 加载小型管线（验证下载、缓存与依赖完整）
python -c "from diffusers import DiffusionPipeline; pipe = DiffusionPipeline.from_pretrained('hf-internal-testing/tiny-stable-diffusion-pipe', safety_checker=None); print('load ok')"

常见问题速查：

现象	可能原因与对策
from_pretrained 报网络错误	检查 HF_HUB_OFFLINE 是否被误设为真；或确认模型是否已缓存
提示缺少 accelerate	未使用 ["torch"] extra，执行 pip install accelerate
版本报错提示 torch 过旧	当前仓库要求 torch>=2.6、huggingface-hub>=1.26.0，升级对应依赖
可编辑安装后 import 失败	确认未删除克隆的 diffusers 目录，且激活了正确的虚拟环境
希望不联网加载	提前在线缓存目标模型，再设置 export HF_HUB_OFFLINE=1

结语

Diffusers 的安装体系围绕“稳定版（pip）→ 最新版（源码）→ 开发版（可编辑）”三个梯度设计，配合环境变量驱动的缓存与遥测机制，可以灵活适配从普通用户到核心贡献者的各类场景。本文所有命令均可直接复制运行，源码佐证集中在 setup.py、hub_utils.py 与 constants.py；若希望深入理解加载链路，可继续阅读 pipeline_utils.py 中 DiffusionPipeline.from_pretrained 对 cache_dir 的完整透传实现。