Errores de importación en ComfyUI: corrige Python y CUDA

TL;DR

• Aísla el Python integrado de ComfyUI — define PYTHONNOUSERSITE=1 y apunta PYTHONPATH a python_embeded\Lib\site-packages para que los paquetes se instalen donde ComfyUI realmente puede encontrarlos.
• Alinea onnxruntime-gpu con la versión de CUDA de tu PyTorch — el onnxruntime-gpu moderno (1.17+) es compatible de forma nativa con CUDA 12.x; ya no es necesario degradar PyTorch a CUDA 11.8 para la mayoría de los usuarios.
• Usa pip.ini para controlar el lugar de instalación — crea %APPDATA%\pip\pip.ini con [global] user = false para evitar que pip escriba en el directorio site-packages de tu usuario.

Por qué fallan las importaciones de ComfyUI

ComfyUI incluye su propio intérprete de Python integrado. Cuando ejecutas pip install sin indicar otra cosa, los paquetes terminan en tu carpeta site-packages de usuario (normalmente AppData\Roaming\Python\PythonX.Y\site-packages en Windows). El intérprete integrado de ComfyUI nunca busca ahí, así que los nodos personalizados muestran ModuleNotFoundError o IMPORT FAILED aunque el parezca estar instalado.

Esto no es un error de ComfyUI — es el comportamiento normal de Python. El intérprete solo busca en las rutas de sys.path. El directorio site-packages de usuario se añade a sys.path automáticamente, a menos que lo desactives con la opción -s o la variable de entorno PYTHONNOUSERSITE.

La documentación de Python lo 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

Corrección 1: evita que los paquetes se instalen en el lugar equivocado

Crea un archivo pip.ini

En Windows, pip lee la configuración por usuario en %APPDATA%\pip\pip.ini. Créalo con:

[global]
user = false

La documentación de pip confirma esta ubicación: "Windows User: %APPDATA%\pip\pip.ini" — https://pip.pypa.io/en/stable/topics/configuration/

El ajuste user = false anula el comportamiento por defecto que, de otro modo, instalaría los paquetes con --user cuando no hay un entorno virtual activo.

Lanza ComfyUI con las variables de entorno correctas

Guarda esto como start_comfyui.bat en el directorio raíz de ComfyUI (donde está main.py):

@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 le dice a Python que omita el directorio site-packages de usuario
• PYTHONPATH apunta al site-packages del entorno integrado
• La opción -s en el comando de Python hace lo mismo que PYTHONNOUSERSITE=1
• Lanza ComfyUI siempre desde este archivo por lotes

Corrección 2: resuelve la incompatibilidad de CUDA de onnxruntime-gpu (aviso de DWPose)

Qué significa el error

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

Aparece cuando onnxruntime-gpu no puede cargar su proveedor de ejecución CUDA. La causa más común: el paquete onnxruntime-gpu se compiló para una versión principal de CUDA distinta de la de tu instalación de PyTorch.

Qué cambió desde 2023

Muchas guías (incluido un popular artículo de Civitai de diciembre de 2023) afirman que onnxruntime-gpu solo es compatible con CUDA 11.8 y recomiendan degradar PyTorch a CUDA 11.8. Ese consejo está desactualizado.

La documentación oficial del proveedor de ejecución CUDA de ONNX Runtime muestra:

Versión de ORT | Versión de CUDA | cuDNN | Disponibilidad ---------------|-----------------|-------|--------------- 1.17.x – 1.26.x | 12.x / 12.8 | 8.x / 9.x | PyPI, NuGet 1.27.x+ | 13.0 | 9.x | PyPI, NuGet (por defecto) Fuente: https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html

Desde ORT 1.17 (mediados de 2023) existe compatibilidad con CUDA 12.x. Desde ORT 1.27 (finales de 2024), pip install onnxruntime-gpu instala por defecto una compilación para CUDA 13.0.

La regla de compatibilidad

onnxruntime-gpu y PyTorch deben compartir la misma versión principal de CUDA y cuDNN para que funcione la precarga de DLL. ONNX Runtime 1.21.0+ incluye onnxruntime.preload_dlls() para cargar las DLL de CUDA/cuDNN desde la instalación de PyTorch, de modo que no necesitas una instalación aparte del kit de herramientas CUDA.

Documentación 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

Qué hacer

Tu CUDA de PyTorch | onnxruntime-gpu recomendado | Acción --------------------|------------------------------|-------- CUDA 12.x (torch 2.x+cu121/124/126/128) | ORT 1.17.x – 1.26.x (CUDA 12.8) | pip install onnxruntime-gpu==1.18.0 o deja que pip lo resuelva CUDA 11.8 (torch 2.x+cu118) | ORT 1.18.x u 1.19.x (CUDA 11.8) | pip install onnxruntime-gpu==1.19.0 CUDA 13.x (torch 2.5+) | ORT 1.27+ (CUDA 13.0) | pip install onnxruntime-gpu (por defecto) No degrades PyTorch a CUDA 11.8 a menos que uses un GPU o controlador antiguo que lo exija. En su lugar, instala la versión de onnxruntime-gpu que coincida.

Para usuarios de ComfyUI portable

Usa el Python integrado de forma explícita:

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

El Python de la distribución portable vive en python_embeded\python.exe — es el intérprete con el que realmente se ejecuta ComfyUI.

Corrección 3: FFMPEG para nodos de vídeo

Si usas WAS Node Suite u otros nodos personalizados de procesamiento de vídeo, FFMPEG debe estar en el PATH del sistema y configurado en was_suite_config.json.

1. Descarga la compilación completa desde https://www.gyan.dev/ffmpeg/builds/ (ffmpeg-git-full.7z)
2. Extrae en C:\ffmpeg para que ffmpeg.exe quede en C:\ffmpeg\bin\ffmpeg.exe
3. Añade C:\ffmpeg\bin al PATH del sistema (PowerShell como administrador):

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

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

Usa barras diagonales incluso en Windows.

Lista de verificación

Después de aplicar las correcciones, lanza con start_comfyui.bat y revisa la consola:

Comprobación | Resultado esperado -------------|-------------------- Los nodos personalizados cargan | Sin líneas IMPORT FAILED ni ModuleNotFoundError DWPose / ControlNet Aux | DWPose: Onnxruntime with acceleration providers detected FFMPEG | Sin avisos de "ffmpeg not found" Aceleración por GPU | Aparece Using cuda:0 (o el índice de tu GPU) Prueba la ubicación de los paquetes:

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

La ruta impresa debe estar dentro de tu carpeta de ComfyUI, en python_embeded\Lib\site-packages.

Errores comunes y correcciones

Síntoma | Causa (con fuente) | Corrección ---------|--------------------|----------- ModuleNotFoundError: No module named 'xyz' | Paquete instalado en el site-packages de usuario, no en el entorno integrado | Instala con .\python_embeded\python.exe -m pip install xyz IMPORT FAILED en un nodo personalizado | Dependencias ausentes en el entorno integrado | Revisa el requirements.txt del nodo e instala cada una con el pip integrado DWPose se ejecuta en CPU con aviso | La versión principal de CUDA de onnxruntime-gpu ≠ la de PyTorch | Instala la versión de onnxruntime-gpu que coincida (ver tabla anterior) Aviso de FFMPEG en la consola | FFMPEG no está en el PATH o la ruta en was_suite_config.json es incorrecta | Añade al PATH del sistema; define ffmpeg_bin_path con barras diagonales torch.version.cuda muestra 12.1 pero ORT necesita 11.8 | Consejo desactualizado — ORT moderno es compatible con CUDA 12.x | Usa ORT 1.17+ en lugar de degradar PyTorch

FAQ

Por qué fallan mis nodos personalizados de ComfyUI al importar, incluso después de pip install?

Porque pip sin entorno virtual instala en tu directorio site-packages de usuario (AppData\Roaming\Python\...), pero ComfyUI se ejecuta desde su Python integrado, que solo ve su propio python_embeded\Lib\site-packages. Define PYTHONNOUSERSITE=1 y usa el pip integrado.

Tengo que degradar PyTorch a CUDA 11.8 para DWPose?

No. Eso era necesario a principios de 2023. Desde ONNX Runtime 1.17 (mediados de 2023), CUDA 12.x es compatible. Desde 1.27 (finales de 2024), el onnxruntime-gpu por defecto se compila para CUDA 13.0. Alinea la versión de ORT con la versión de CUDA de tu PyTorch.

Dónde va pip.ini en Windows?

En %APPDATA%\pip\pip.ini. La documentación de pip lo indica como la ubicación del archivo de configuración por usuario para Windows 7 y versiones posteriores.

Qué hace exactamente PYTHONNOUSERSITE=1?

Le dice al intérprete de Python que no añada el directorio site-packages de usuario a sys.path. Es un comportamiento documentado de CPython — no específico de ComfyUI.

Puedo usar un entorno virtual en lugar del Python integrado?

Puedes, pero ComfyUI portable está diseñado para ejecutarse con su intérprete integrado. Usar el Python integrado con PYTHONNOUSERSITE=1 y el PYTHONPATH correcto es más sencillo y coincide con la configuración prevista de la distribución.

Por qué barras diagonales en was_suite_config.json?

El analizador de configuración espera barras diagonales. Las barras invertidas son caracteres de escape en las cadenas JSON y rompen la ruta.

Cómo sé qué versión de CUDA usa mi PyTorch?

Ejecuta:

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

Una salida como 12.1 u 11.8 indica la versión principal.secundaria de CUDA.

Tabla de decisión: qué onnxruntime-gpu instalar

Si tu PyTorch muestra… | Instala este onnxruntime-gpu | Comando pip ----------------------|------------------------------|------------- 12.1 – 12.8 (cu121/cu124/cu126/cu128) | 1.17.x – 1.26.x (CUDA 12.8) | pip install onnxruntime-gpu==1.18.0 11.8 (cu118) | 1.18.x u 1.19.x (CUDA 11.8) | pip install onnxruntime-gpu==1.19.0 13.0+ (cu130) | 1.27+ (CUDA 13.0) | pip install onnxruntime-gpu Fuente de la matriz de versiones de CUDA: https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html Fuente de la disponibilidad de ruedas de PyTorch: https://download.pytorch.org/whl/torch_stable.html

• Guía de desarrollo de nodos personalizados de ComfyUI
• Gestión de múltiples versiones de PyTorch con entornos virtuales
• Configuración de FFMPEG para flujos de vídeo con IA

Marcadores de posición de medios

Fuentes

• docs.python.org
• pip.pypa.io
• onnxruntime.ai
• download.pytorch.org
• civitai.com
• civitai.com
• civitai.com