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.

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() 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, 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.

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.

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.

export HF_HUB_DISABLE_SHARED_BLOBS=1

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