diffusers/v0.43.0/pt/installation.md

Instalação

Diffusers requer Python 3.10+ e é testado com PyTorch 2.6+. Instale PyTorch de acordo com seu sistema e configuração.

Crie um ambiente virtual para facilitar o gerenciamento de projetos separados e evitar problemas de compatibilidade entre dependências. Use o uv, um gerenciador de pacotes e projetos Python baseado em Rust, para criar um ambiente virtual e instalar o Diffusers.

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

Instale o Diffusers com um dos seguintes métodos.

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.

nvidia-smi

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

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

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 e faremos o possível para resolvê-lo o mais rápido possível.

Verifique se o Accelerate está instalado.

uv pip install accelerate

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

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 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".

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.

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.

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

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.

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 ou HF_HUB_CACHE ou configurando o parâmetro cache_dir em métodos como from_pretrained().

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

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 como 1 para impedir que o Diffusers se conecte à internet.

export HF_HUB_OFFLINE=1

Para mais detalhes sobre a gestão e a limpeza do cache, consulte o guia Entenda o cache.

Registro de telemetria

O Diffusers coleta informações de telemetria durante as solicitações de 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.

export HF_HUB_DISABLE_TELEMETRY=1

set HF_HUB_DISABLE_TELEMETRY=1