# Instalação

Diffusers requer Python 3.10+ e é testado com PyTorch 2.6+. Instale [PyTorch](https://pytorch.org/get-started/locally/) de acordo com seu sistema e configuração.

Crie um [ambiente virtual](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) para facilitar o gerenciamento de projetos separados e evitar problemas de compatibilidade entre dependências. Use o [uv](https://docs.astral.sh/uv/), um gerenciador de pacotes e projetos Python baseado em Rust, para criar um ambiente virtual e instalar o Diffusers.

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

Instale o Diffusers com um dos seguintes métodos.

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

Para instalar o Diffusers com PyTorch em dispositivos NVIDIA Spark (como um laptop RTX Spark) que executam ARM64, instale o PyTorch a partir do índice PyPI da NVIDIA. Esses dispositivos exigem as compilações ARM64 do PyTorch da NVIDIA, que não estão disponíveis no índice PyPI padrão nem no índice padrão de wheels do PyTorch.

Execute o comando abaixo para verificar se o seu sistema detecta uma GPU da NVIDIA.

```bash
nvidia-smi
```

Instale o PyTorch a partir do índice PyPI da NVIDIA e, em seguida, instale o Diffusers.

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

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

Uma instalação a partir do código-fonte instala a versão `main` em vez da versão `stable` mais recente. A versão `main` é útil para se manter atualizado com as últimas alterações, mas nem sempre é estável. Se você encontrar um problema, abra uma [Issue](https://github.com/huggingface/diffusers/issues/new/choose) e faremos o possível para resolvê-lo o mais rápido possível.

Verifique se o [Accelerate](https://huggingface.co/docs/accelerate/index) está instalado.

```bash
uv pip install accelerate
```

Instale o Diffusers a partir do código-fonte com o comando abaixo.

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

Instale com extras quando precisar deles. `diffusers["torch"]` inclui PyTorch e Accelerate. Outros extras cobrem backends de quantização, treinamento e documentação. Consulte [`setup.py`](https://github.com/huggingface/diffusers/blob/main/setup.py) para a lista completa.

## Dispositivos

Diffusers funciona em qualquer acelerador suportado pelo PyTorch. Os exemplos ao longo da documentação usam `"cuda"` porque é a configuração mais comum, mas nada é específico do CUDA. Substitua a string do dispositivo pelo seu hardware, como `"xpu"` para GPUs da Intel, `"mps"` para Apple silicon ou `"cpu"`.

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

Para escolher o dispositivo em tempo de execução em vez de fixá-lo no código, use [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"
```

## Instalação editável

Uma instalação editável é recomendada para fluxos de trabalho de desenvolvimento ou se você estiver usando a versão `main` do código-fonte. Um link especial é criado entre o repositório clonado e os caminhos da biblioteca Python. Isso evita a reinstalação de um pacote após cada alteração.

Clone o repositório e instale o Diffusers com os seguintes comandos.

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

> [!WARNING]
> Você deve manter a pasta `diffusers` se quiser continuar usando a biblioteca com a instalação editável.

Atualize seu repositório clonado para a versão mais recente do Diffusers com o comando abaixo.

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

## Cache

Os pesos e arquivos do modelo são baixados do Hub para um cache, que geralmente é o seu diretório inicial. Altere a localização do cache com as variáveis de ambiente [HF_HOME](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhome) ou [HF_HUB_CACHE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache) ou configurando o parâmetro `cache_dir` em métodos como [from_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained).

```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"
)
```

Arquivos em cache permitem que você use o Diffusers offline. Defina a variável de ambiente [HF_HUB_OFFLINE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhuboffline) como `1` para impedir que o Diffusers se conecte à internet.

```shell
export HF_HUB_OFFLINE=1
```

Para mais detalhes sobre a gestão e a limpeza do cache, consulte o guia [Entenda o cache](https://huggingface.co/docs/huggingface_hub/guides/manage-cache).

## Registro de telemetria

O Diffusers coleta informações de telemetria durante as solicitações de [from_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained). Os dados coletados incluem a versão do Diffusers e do PyTorch, a classe do modelo ou pipeline solicitada e o caminho para um checkpoint pré-treinado, caso ele esteja hospedado no Hub.

Esses dados de uso nos ajudam a depurar problemas e priorizar novos recursos. A telemetria é enviada apenas ao carregar modelos e pipelines do Hub e não é coletada se você estiver carregando arquivos locais.

Desative e desabilite a coleta de telemetria com a variável de ambiente [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
```