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

nvidia-smi

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

conda install -c conda-forge diffusers

uv pip install accelerate

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