Erros de importação no ComfyUI: Python e CUDA

TL;DR

• Isole o Python embutido do ComfyUI — defina PYTHONNOUSERSITE=1 e aponte PYTHONPATH para python_embeded\Lib\site-packages para que pacotes sejam instalados onde o ComfyUI consegue encontrá-los.
• Alinhe o onnxruntime-gpu à sua versão CUDA do PyTorch — onnxruntime-gpu moderno (1.17+) suporta CUDA 12.x nativamente; fazer downgrade do PyTorch para CUDA 11.8 não é mais necessário para a maioria dos usuários.
• Use pip.ini para controlar o local de instalação — crie %APPDATA%\pip\pip.ini com [global] user = false para impedir que o pip escreva no seu diretório user site-packages.

Por que as importações do ComfyUI falham

O ComfyUI vem com seu próprio interpretador Python embutido. Quando você roda pip install sem dizer o contrário, os pacotes vão para a pasta user site-packages (tipicamente AppData\Roaming\Python\PythonX.Y\site-packages no Windows). O interpretador embutido do ComfyUI nunca olha lá, então custom nodes reportam ModuleNotFoundError ou IMPORT FAILED mesmo que o pacote pareça instalado. Fonte: https://civitai.com/articles/4172

Isso não é um bug do ComfyUI — é como o Python funciona. O interpretador só busca caminhos em sys.path. O diretório user site-packages é adicionado a sys.path automaticamente, a menos que você o desative com a flag -s ou a variável de ambiente PYTHONNOUSERSITE.

A documentação do Python confirma: "If this is set, Python won't add the user site-packages directory to sys.path." — https://docs.python.org/3/using/cmdline.html

Correção 1: Impedir pacotes de instalar no local errado

Criar um arquivo pip.ini

No Windows, o pip lê a configuração por usuário em %APPDATA%\pip\pip.ini. Crie-o com:

[global]
user = false

A documentação do pip confirma este local: "Windows User: %APPDATA%\pip\pip.ini" — https://pip.pypa.io/en/stable/topics/configuration/

A configuração user = false sobrescreve o comportamento padrão que instalaria pacotes com --user quando não estiver em um ambiente virtual.

Iniciar o ComfyUI com as variáveis de ambiente certas

Salve isto como start_comfyui.bat no diretório raiz do ComfyUI (onde main.py está):

@echo off
setlocal
set PYTHONNOUSERSITE=1
set PYTHONPATH=%~dp0python_embeded\Lib\site-packages
.\python_embeded\python.exe -s ComfyUI\main.py --windows-standalone-build
endlocal

• PYTHONNOUSERSITE=1 diz ao Python para pular o diretório user site-packages
• PYTHONPATH aponta para o site-packages do ambiente embutido
• A flag -s no comando python faz a mesma coisa que PYTHONNOUSERSITE=1
• Sempre inicie o ComfyUI através deste arquivo batch

Correção 2: Resolver o mismatch de CUDA no onnxruntime-gpu (aviso DWPose)

O que o erro significa

UserWarning: Onnxruntime not found or doesn't come with acceleration providers,
switch to OpenCV with CPU device. DWPose might run very slowly

Isso aparece quando o onnxruntime-gpu não consegue carregar seu provedor de execução CUDA. A causa mais comum: o pacote onnxruntime-gpu foi compilado para uma versão major de CUDA diferente da sua instalação do PyTorch.

O que mudou desde 2023

Muitos guias (incluindo um artigo popular da Civitai de dezembro de 2023) afirmam que o onnxruntime-gpu só suporta CUDA 11.8 e recomendam fazer downgrade do PyTorch para CUDA 11.8. Esse conselho está desatualizado. Fonte: https://civitai.com/articles/3093

A documentação oficial do ONNX Runtime CUDA Execution Provider mostra:

Fonte: https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html

Desde ORT 1.17 (meados de 2023), CUDA 12.x é suportado. Desde ORT 1.27 (final de 2024), o pip install onnxruntime-gpu padrão puxa um build CUDA 13.0.

A regra de compatibilidade

onnxruntime-gpu e PyTorch devem compartilhar a mesma versão major de CUDA e cuDNN para que o pré-carregamento de DLLs funcione. ONNX Runtime 1.21.0+ fornece onnxruntime.preload_dlls() para carregar DLLs CUDA/cuDNN da instalação do PyTorch, então você não precisa de uma instalação separada do CUDA toolkit.

Documentação oficial: "The onnxruntime-gpu package is designed to work seamlessly with PyTorch, provided both are built against the same major version of CUDA and cuDNN." — https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html

O que fazer

Não faça downgrade do PyTorch para CUDA 11.8 a menos que esteja em uma GPU/driver mais antigo que exija isso. Instale a versão correspondente do onnxruntime-gpu em vez disso.

Para usuários do ComfyUI portable

Use o Python embutido explicitamente:

.\python_embeded\python.exe -m pip install onnxruntime-gpu==1.18.0

O Python da distribuição portable fica em python_embeded\python.exe — este é o interpretador que o ComfyUI realmente executa.

Correção 3: FFMPEG para nodes de vídeo

Se você usa WAS Node Suite ou outros custom nodes de processamento de vídeo, o FFMPEG deve estar no PATH do sistema e configurado no was_suite_config.json.

1. Baixe o build completo de https://www.gyan.dev/ffmpeg/builds/ (ffmpeg-git-full.7z)
2. Extraia para C:\ffmpeg de forma que ffmpeg.exe fique em C:\ffmpeg\bin\ffmpeg.exe
3. Adicione C:\ffmpeg\bin ao PATH do sistema (PowerShell admin):

   [Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\ffmpeg\bin", "Machine")

1. Edite ComfyUI\custom_nodes\was-node-suite-comfyui\was_suite_config.json:

Use barras normais mesmo no Windows.

Checklist de verificação

Após aplicar as correções, inicie via start_comfyui.bat e verifique o console:

Teste localização de pacote:

.\python_embeded\python.exe -m pip install emoji
.\python_embeded\python.exe -c "import emoji; print(emoji.__file__)"

O caminho impresso deve estar dentro da sua pasta ComfyUI sob python_embeded\Lib\site-packages.

Erros comuns e correções

FAQ

Por que meus custom nodes do ComfyUI falham ao importar mesmo após pip install?

Porque pip sem ambiente virtual instala no seu diretório user site-packages (AppData\Roaming\Python\...), mas o ComfyUI roda a partir de seu Python embutido que só vê seu próprio python_embeded\Lib\site-packages. Defina PYTHONNOUSERSITE=1 e use o pip embutido.

Preciso fazer downgrade do PyTorch para CUDA 11.8 para o DWPose?

Não. Isso era necessário no início de 2023. Desde ONNX Runtime 1.17 (meados de 2023), CUDA 12.x é suportado. Desde 1.27 (final de 2024), o onnxruntime-gpu padrão é compilado para CUDA 13.0. Alinhe a versão do ORT à versão CUDA do seu PyTorch em vez disso.

Onde o pip.ini vai no Windows?

%APPDATA%\pip\pip.ini. A documentação do pip lista isso como o local do arquivo de configuração por usuário para Windows 7 e posteriores.

O que PYTHONNOUSERSITE=1 faz de verdade?

Diz ao interpretador Python para não adicionar o diretório user site-packages ao sys.path. Isso é comportamento documentado do CPython — não é específico do ComfyUI.

Posso usar um ambiente virtual em vez do Python embutido?

Pode, mas o ComfyUI portable foi projetado para rodar no interpretador embutido. Usar o Python embutido com PYTHONNOUSERSITE=1 e PYTHONPATH correto é mais simples e corresponde à configuração pretendida da distribuição.

Por que barras normais no was_suite_config.json?

O parser de configuração espera barras normais. Barras invertidas são caracteres de escape em strings JSON e quebram o caminho.

Como sei qual versão CUDA meu PyTorch usa?

Rode:

.\python_embeded\python.exe -c "import torch; print(torch.version.cuda)"

Saída como 12.1 ou 11.8 indica a versão major.minor do CUDA.

Tabela de decisão: qual onnxruntime-gpu instalar

Fonte para matriz de versão CUDA: https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html Fonte para disponibilidade de wheels PyTorch: https://download.pytorch.org/whl/torch_stable.html

• Guia de desenvolvimento de custom nodes ComfyUI
• Gerenciando múltiplas versões do PyTorch com ambientes virtuais
• Configuração FFMPEG para workflows de vídeo com IA