# 安装

Diffusers 需要 Python 3.10+，并已在 PyTorch 2.6+ 上进行测试。请根据您的系统和配置安装 [PyTorch](https://pytorch.org/get-started/locally/)。

创建一个[虚拟环境](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/)，以便更轻松地管理独立项目，并避免依赖项之间的兼容性问题。使用基于 Rust 的 Python 包和项目管理器 [uv](https://docs.astral.sh/uv/) 来创建虚拟环境并安装 Diffusers。

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

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

```bash
uv pip install diffusers["torch"] transformers
```

要在运行 ARM64 的 NVIDIA Spark 设备（例如 RTX Spark 笔记本电脑）上安装基于 PyTorch 的 Diffusers，请从 NVIDIA PyPI 索引安装 PyTorch。这些设备需要 NVIDIA 提供的 PyTorch ARM64 构建版本，而该版本在默认 PyPI 索引或标准 PyTorch wheel 索引中不可用。

运行以下命令以检查您的系统是否检测到 NVIDIA GPU。

```bash
nvidia-smi
```

从 NVIDIA PyPI 索引安装 PyTorch，然后安装 Diffusers。

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

```bash
conda install -c conda-forge diffusers
```

源码安装会安装 `main` 版本，而不是最新的 `stable` 版本。`main` 版本有助于您跟进最新变更，但可能并不总是稳定。如果您遇到问题，请提交一个 [Issue](https://github.com/huggingface/diffusers/issues/new/choose)，我们会尽快尝试解决。

请确保已安装 [Accelerate](https://huggingface.co/docs/accelerate/index)。

```bash
uv pip install accelerate
```

使用以下命令从源代码安装 Diffusers。

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

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

## 设备

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

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

要在运行时选择设备而不是硬编码，请使用 [torch.accelerator](https://docs.pytorch.org/docs/stable/accelerator.html)。

```py
import torch

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

## 可编辑安装

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

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

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

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

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

```bash
cd ~/diffusers/
git pull
```

## 缓存

模型权重和文件会从 Hub 下载到缓存目录，通常位于您的主目录。您可以通过设置 [HF_HOME](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhome) 或 [HF_HUB_CACHE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache) 环境变量，或在 [from_pretrained()](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) 等方法中配置 `cache_dir` 参数来更改缓存位置。

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

```py
from diffusers import DiffusionPipeline

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

缓存文件可让您离线使用 Diffusers。将 [HF_HUB_OFFLINE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhuboffline) 环境变量设置为 `1`，即可阻止 Diffusers 连接互联网。

```shell
export HF_HUB_OFFLINE=1
```

如需了解有关管理和清理缓存的更多详细信息，请参阅[了解缓存](https://huggingface.co/docs/huggingface_hub/guides/manage-cache)指南。

## 遥测日志

Diffusers 会在 [from_pretrained()](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) 请求期间收集遥测信息。所收集的数据包括 Diffusers 和 PyTorch 的版本、请求的模型或 pipeline 类，以及如果预训练检查点托管在 Hub 上，则还包括其路径。

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

使用 [HF_HUB_DISABLE_TELEMETRY](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubdisabletelemetry) 环境变量可退出并禁用遥测数据收集。

```bash
export HF_HUB_DISABLE_TELEMETRY=1
```

```bash
set HF_HUB_DISABLE_TELEMETRY=1
```