# 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/main/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).

### Compartilhar arquivos entre repositórios

O cache mantém uma cópia de um arquivo, mesmo quando vários repositórios do Hub o contêm. Muitos pipelines usam o mesmo codificador de texto, como o T5. Se o repositório de um segundo pipeline tiver os mesmos arquivos de codificador de texto que você já baixou, [from_pretrained()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) usa a cópia em disco em vez de baixá-lo novamente. O Diffusers requer `huggingface_hub>=1.32.0`, que ativa o compartilhamento de arquivos por padrão.

O cache corresponde aos arquivos pelo seu hash [Xet](https://huggingface.co/docs/hub/xet/index), e não pelo nome do repositório ou do modelo. Um checkpoint particionado é correspondido partição por partição, de modo que as partições que correspondem são compartilhadas, mesmo que as outras sejam diferentes.

Um arquivo é compartilhado apenas quando todas as seguintes condições forem verdadeiras:

- Ambos os repositórios armazenam o arquivo com Xet.
- Ambos os downloads usam o mesmo diretório de cache, definido por `HF_HUB_CACHE` ou `cache_dir`.
- O sistema de arquivos suporta links simbólicos.
- Os arquivos são idênticos byte a byte. Converter para um dtype diferente, salvar em um formato diferente ou redividir (resharding) altera o hash.

> [!NOTE]
> Arquivos baixados com uma versão anterior do `huggingface_hub` não são compartilhados com novos downloads. Somente arquivos baixados com a versão 1.32.0 ou posterior são adicionados ao armazenamento compartilhado.

O compartilhamento de arquivos economiza tempo de download e espaço em disco, mas não memória. Para usar um modelo carregado em vários pipelines, consulte [Reutilizando modelos em vários pipelines](./using-diffusers/loading#reusing-models-in-multiple-pipelines).

Para desativar o compartilhamento de arquivos, defina `HF_HUB_DISABLE_SHARED_BLOBS=1`. O carregamento continua funcionando e cada repositório mantém sua própria cópia.

```shell
export HF_HUB_DISABLE_SHARED_BLOBS=1
```

## Registro de telemetria

O Diffusers coleta informações de telemetria durante as solicitações de [from_pretrained()](/docs/diffusers/main/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
```