Instalar Stable Diffusion localmente parece simples até a primeira execução falhar. E ela falha muito, porque o que você está instalando não é um programa, é um conjunto de bibliotecas de Python que precisam concordar entre si, com o seu sistema e com a sua placa de vídeo.
Resposta direta: a maioria das falhas cai em quatro categorias. Ambiente de Python errado ou com dependências quebradas, driver e biblioteca de GPU incompatíveis, arquivos de modelo ausentes ou mal posicionados, e configuração inadequada para a memória disponível. A mensagem no terminal aponta para uma delas quase sempre. Leia antes de reinstalar.
A regra que resolve metade dos casos
Antes de qualquer coisa, entenda o que você está olhando. Uma instalação local do Stable Diffusion tem camadas: o Python, um ambiente virtual isolado, as bibliotecas de aprendizado de máquina, a interface web e os arquivos de modelo. Cada camada pode falhar sozinha, e cada uma produz um sintoma diferente.
A regra prática é ler o terminal de baixo para cima. A última linha diz o que aconteceu, as linhas acima dizem onde. Muita gente vê um bloco de texto vermelho, entra em pânico e reinstala tudo. Na maioria das vezes, aquele bloco inteiro é apenas o caminho até o erro, e o erro em si cabe em uma frase. Copie essa frase, entenda o substantivo principal dela e você já reduziu o espaço de busca em noventa por cento.
Se você está montando o ambiente agora, seguir um caminho testado evita boa parte do sofrimento. O nosso guia do Stable Diffusion Forge em português cobre a instalação passo a passo em uma distribuição que já resolve várias dessas incompatibilidades por padrão.
Erros de Python e dependências
Esta é a categoria mais comum e a mais mal compreendida. O problema quase nunca é o Python em si, é a confusão entre ambientes.
Versão de Python incompatível
As bibliotecas usadas por Stable Diffusion não acompanham imediatamente as versões mais novas de Python. Se você instalou a versão mais recente disponível, é bem provável que alguma dependência não tenha pacote compilado para ela, e a instalação falha ao tentar compilar do zero. O sintoma é um erro longo durante a instalação de um pacote específico, cheio de referências a compilador. A correção é instalar uma versão de Python que a comunidade da ferramenta indica como suportada, e apontar a instalação para ela.
Ambiente virtual ignorado
Este é o clássico. A ferramenta cria um ambiente isolado e instala tudo lá dentro. Você abre outro terminal, instala um pacote e ele vai para o Python do sistema. Nada muda, porque a ferramenta nunca olha para lá. Sempre confirme que o ambiente virtual está ativo antes de instalar qualquer coisa. Se você não sabe dizer se está ativo, provavelmente não está.
Dependências em conflito
Extensões e instalações manuais forçam versões específicas de bibliotecas, e duas exigências incompatíveis produzem um ambiente que instala mas não roda. O sintoma é um erro de importação ou de atributo inexistente em uma biblioteca conhecida. Nesse ponto, tentar consertar pacote por pacote costuma custar mais que apagar o ambiente virtual e deixar a ferramenta recriá-lo. Apagar o ambiente virtual não apaga seus modelos nem suas saídas, desde que eles estejam nas pastas próprias.
Espaço em disco e caminho com acento
Dois detalhes bobos que quebram instalações. Falta de espaço durante o download das bibliotecas gera erros que parecem de rede. E instalar em um caminho com acentos, espaços incomuns ou caracteres especiais causa falhas aleatórias em ferramentas que não tratam isso bem. Instale em um caminho curto e simples, de preferência na raiz de um disco.
A interface abre em branco
Você roda o script, o terminal diz que o servidor subiu, você abre o endereço local e vê uma página vazia ou apenas o cabeçalho. Isso não é falha de geração, é falha de carregamento da interface.
Comece recarregando com cache limpo, porque interfaces web guardam recursos antigos e uma atualização da ferramenta pode deixar arquivos incompatíveis em cache. Se não resolver, desative extensões do navegador na aba, principalmente bloqueadores, que frequentemente cortam scripts locais. Depois teste em outro navegador e em janela anônima. Se em nenhum lugar carrega, olhe o terminal de novo: uma extensão da própria ferramenta pode ter quebrado a construção da interface, e nesse caso o servidor sobe mas a página não monta.
O teste definitivo é iniciar com as extensões desativadas. Se a interface aparece, você achou o culpado e basta reativar uma por vez. Esse padrão vale para praticamente toda ferramenta com sistema de extensões, incluindo o ComfyUI, onde o comportamento é idêntico.
Checkpoints que não são detectados
Se o seletor de modelos aparece vazio ou não mostra o arquivo que você baixou, verifique em ordem: pasta correta, arquivo íntegro, lista atualizada.
Pasta correta significa a subpasta de checkpoints, e não a pasta de LoRAs, embeddings ou VAEs. Cada tipo tem seu lugar, e um arquivo no lugar errado é invisível. Arquivo íntegro significa tamanho compatível com o anunciado na origem, porque downloads truncados são comuns em arquivos grandes. Lista atualizada significa que a interface leu a pasta depois de você copiar o arquivo. A maioria das interfaces tem um botão de atualizar a lista de modelos, e quando ele não resolve, reiniciar o servidor resolve.
Um caso à parte: o modelo aparece, você seleciona e a interface trava ou devolve erro ao carregar. Isso é diferente de não aparecer. Aqui o arquivo foi encontrado mas não pôde ser aberto, o que aponta para corrupção, formato não suportado pela sua versão, ou memória insuficiente para carregar aquele modelo específico. Modelos maiores exigem mais memória só para entrar na placa, antes mesmo de gerar qualquer coisa.
Se você baixa modelos de repositórios comunitários com frequência, aprender a ler a ficha técnica antes de baixar economiza muito tempo. O nosso tutorial do Civitai em português explica o que cada campo significa e como saber se aquele arquivo serve para o seu setup.
Imagem preta, cinza ou com ruído
Saída preta é o erro mais assustador e um dos mais fáceis de corrigir, porque tem um conjunto pequeno de causas.
A primeira é VAE ausente ou incompatível. O VAE é responsável por transformar a representação interna em imagem visível, e quando ele falha o resultado é preto ou completamente distorcido. Carregar um VAE conhecido e testar de novo elimina essa hipótese em um minuto.
A segunda é precisão numérica. Algumas combinações de placa e biblioteca produzem valores inválidos em meia precisão, e o resultado é uma imagem vazia. As interfaces oferecem opções de inicialização que forçam precisão total ou modos de compatibilidade. Elas custam desempenho, mas servem como teste diagnóstico decisivo.
A terceira é filtro de segurança de conteúdo. Algumas distribuições substituem a imagem por um quadro preto quando o classificador interno é acionado. Se o preto aparece só em certos prompts e nunca em paisagens, essa é a causa, e não um defeito técnico. Quem trabalha com conteúdo adulto encontra isso com frequência, e a nossa lista de melhores IAs sem restrições mostra quais plataformas não impõem esse tipo de filtro.
A quarta é ruído puro na saída, sem forma nenhuma. Isso normalmente indica número de passos muito baixo, amostrador incompatível com o modelo, ou escala de orientação em valor extremo. Volte aos padrões antes de investigar qualquer outra coisa.
Falta de memória de vídeo
Se a geração começa e morre, ou se o sistema inteiro engasga, você está no limite da memória de vídeo. A ordem de correção vai do mais barato ao mais caro.
Feche navegadores com muitas abas, players e programas de vídeo chamada, que consomem memória de vídeo mesmo parados. Reduza a resolução, porque o consumo cresce muito mais rápido que a área da imagem. Gere uma imagem por vez em vez de lotes. Desligue upscale e refino no mesmo fluxo, executando essas etapas separadamente depois. Só então recorra aos modos de economia de memória que a interface oferece na inicialização, que movem partes do modelo entre a placa e a memória do sistema em troca de velocidade.
Também vale ajustar a expectativa ao hardware. Existe uma diferença enorme entre o que é possível e o que é confortável em cada faixa de placa. A nossa análise de RTX 3060 com Stable Diffusion no Brasil mostra resoluções e fluxos realistas para placas de entrada, o que evita insistir em configurações que nunca vão caber.
Quando a máquina simplesmente não dá conta, alugar GPU por hora costuma sair mais barato que trocar de placa, principalmente para uso esporádico. O nosso tutorial de RunPod em português cobre como subir o mesmo ambiente em uma máquina remota e manter o fluxo de trabalho.
Driver, GPU e o erro que não é seu
Uma parte das falhas vem da relação entre driver de vídeo e biblioteca de computação. Sintomas típicos são a ferramenta não reconhecer a placa e cair para processamento em CPU, que funciona mas é lentíssimo, ou erros mencionando dispositivo indisponível.
Verifique primeiro se a ferramenta está mesmo usando a GPU. As interfaces informam isso na inicialização. Se ela caiu para CPU, o problema é de detecção, não de desempenho. Atualizar o driver da placa resolve parte dos casos, mas atenção ao inverso: driver muito novo às vezes quebra bibliotecas que ainda não foram atualizadas. Se tudo funcionava e parou depois de uma atualização de driver, voltar para a versão anterior é uma hipótese legítima.
Em notebooks com placa integrada e dedicada, existe ainda o caso do sistema entregar a integrada para o processo. Forçar o uso da placa dedicada nas configurações gráficas do sistema resolve, e o sintoma é justamente desempenho absurdamente baixo sem erro nenhum.
Quando o problema é o prompt e não a instalação
Nem toda decepção é bug. Imagem que ignora o pedido, anatomia estranha e composição confusa não são falhas de instalação, são características do modelo e do prompt.
Antes de mexer em configuração, faça o teste de controle: um prompt curto e claro, um modelo popular, parâmetros padrão. Se sai algo coerente, a instalação está boa. A partir daí o trabalho é de conteúdo, não de infraestrutura, e o retorno vem de aprender vocabulário de prompt e pesos. A nossa biblioteca de prompts NSFW em português serve como base para construir esse repertório sem começar do zero.
Quem quer resultado consistente em um estilo ou personagem específico acaba precisando de treinamento próprio, e aí o assunto é outro. O nosso guia de como treinar LoRA em português explica quando isso compensa e quando é excesso de esforço para um problema que o prompt resolve.
Tabela de sintomas e correções
| Sintoma | Causa provável | Correção |
|---|---|---|
| Instalação falha ao compilar um pacote | Versão de Python sem pacote pronto | Usar a versão de Python indicada como suportada |
| Pacote instalado mas erro continua | Instalação foi para o Python do sistema | Ativar o ambiente virtual antes de instalar |
| Servidor sobe e a página fica em branco | Extensão quebrando a interface ou cache antigo | Iniciar sem extensões e recarregar sem cache |
| Seletor de modelos vazio | Arquivo em pasta errada ou lista desatualizada | Conferir a subpasta correta e reiniciar o servidor |
| Erro ao selecionar um modelo específico | Arquivo truncado ou memória insuficiente | Conferir tamanho do arquivo e testar modelo menor |
| Imagem sai preta | VAE ausente, precisão numérica ou filtro de conteúdo | Trocar o VAE e testar em modo de precisão total |
| Geração extremamente lenta | Processamento caiu para CPU | Verificar detecção da GPU e forçar a placa dedicada |
| Processo morre no meio da geração | Memória de vídeo esgotada | Reduzir resolução, gerar uma imagem por vez |
Checklist de diagnóstico, do mais rápido ao mais lento
- Leia a última linha do terminal e identifique o substantivo principal do erro.
- Recarregue a interface sem cache e teste em janela anônima.
- Inicie a ferramenta com todas as extensões desativadas.
- Confirme na inicialização se a GPU foi detectada ou se caiu para CPU.
- Gere com prompt simples, modelo conhecido e parâmetros padrão.
- Reduza resolução e lote ao mínimo para descartar memória.
- Troque o VAE se a imagem sair preta ou distorcida.
- Confira se o arquivo de modelo está na subpasta certa e com o tamanho esperado.
- Verifique se o ambiente virtual está ativo antes de instalar qualquer pacote.
- Apague o ambiente virtual e deixe a ferramenta recriar as dependências.
- Atualize ou reverta o driver de vídeo, dependendo de quando o problema começou.
- Só no fim, reinstale em pasta nova com caminho curto e sem acentos.
Quando local deixa de compensar
Rodar localmente dá controle total, privacidade e custo marginal zero por imagem. Em troca, você assume o papel de administrador de sistema. Para muita gente essa troca vale a pena. Para outra parte, não.
O sinal de que não vale é simples: se nas últimas semanas você passou mais tempo consertando do que criando, e se cada atualização vira um dia perdido, o problema deixou de ser técnico e virou de custo de oportunidade. Nesse ponto existem dois caminhos razoáveis.
O primeiro é manter o mesmo fluxo em GPU alugada, o que elimina limitações de hardware sem abrir mão do controle. O segundo é usar uma plataforma pronta para o volume do dia a dia e deixar a instalação local para experimentos. Uma opção direta é o AI Nudez, que gera sem exigir ambiente, driver ou biblioteca nenhuma, e serve bem como plano B enquanto você resolve a instalação com calma.
Prevenção: o que evita reinstalar tudo de novo
Anote o que você instalou e quando. A maioria das quebras acontece logo depois de alguma mudança, e um registro simples transforma um mistério em uma linha do tempo. Não atualize a ferramenta, as extensões e o driver na mesma sessão, porque assim você perde a capacidade de saber qual mudança causou o problema.
Mantenha modelos e imagens geradas em pastas fora da instalação, ou apontadas por configuração para um caminho externo. Isso torna reinstalar uma operação de minutos em vez de horas, e remove o medo de apagar o ambiente virtual quando ele estiver quebrado. E teste uma geração simples depois de cada mudança, para que o intervalo entre funcionando e quebrado seja sempre curto.
Por fim, tenha um plano B configurado antes de precisar dele. Ter uma conta funcionando em um serviço online como o AI Nudez significa que uma instalação quebrada atrasa você, mas não para você. Isso muda a forma como você lida com o problema, porque depurar sem pressa é infinitamente mais eficiente do que depurar com prazo em cima.
Perguntas frequentes
Por que a instalação do Stable Diffusion falha na primeira execução?
Normalmente porque a versão de Python instalada não tem pacotes prontos para alguma dependência, e o instalador tenta compilar do zero e falha. Instalar a versão de Python indicada como suportada resolve a maior parte desses casos. Espaço em disco insuficiente e caminhos com acentos também causam falhas parecidas.
Instalei o pacote que o erro pedia e nada mudou. Por quê?
Quase certamente o pacote foi para o Python do sistema, enquanto a ferramenta usa um ambiente virtual isolado. Ative o ambiente virtual no mesmo terminal antes de instalar qualquer coisa. Se você não tem certeza de que ele está ativo, presuma que não está e ative de novo.
A interface abre em branco. O que fazer primeiro?
Recarregue sem cache, teste em janela anônima e desative as extensões do navegador na aba. Se continuar em branco, inicie a ferramenta com as extensões dela desativadas, porque uma extensão quebrada permite o servidor subir mas impede a interface de montar.
Por que minhas imagens saem completamente pretas?
As causas mais comuns são VAE ausente ou incompatível, problemas de precisão numérica em certas combinações de placa e biblioteca, e filtro de conteúdo que substitui a imagem. Troque o VAE, teste em modo de precisão total e observe se o preto aparece só em alguns prompts, o que indica filtro.
Como saber se o Stable Diffusion está usando minha placa de vídeo?
A própria ferramenta informa na inicialização qual dispositivo foi detectado. Se ela caiu para CPU, a geração fica muito lenta sem apresentar erro. Em notebooks, confira também se o sistema não está entregando a placa integrada ao processo em vez da dedicada.
Meu checkpoint não aparece na lista. Onde está o erro?
Na ordem: pasta errada, arquivo truncado, lista não atualizada. Cada tipo de arquivo tem sua subpasta própria e um checkpoint fora dela é invisível. Compare o tamanho do arquivo com o anunciado na origem e reinicie o servidor para forçar a leitura da pasta.
Posso apagar o ambiente virtual sem perder meus modelos?
Sim, desde que modelos e imagens geradas estejam nas pastas próprias e não dentro do ambiente virtual. Apagar o ambiente e deixar a ferramenta recriar as dependências costuma ser mais rápido do que tentar resolver conflitos de versão pacote por pacote.
Vale a pena insistir em rodar local com placa fraca?
Depende do seu objetivo. Para aprender e experimentar, sim, com resolução baixa e uma imagem por vez. Para produzir em volume ou com prazo, alugar GPU por hora ou usar uma plataforma online costuma render muito mais resultado pelo mesmo esforço.
