A comprehensive step-by-step guide for installing Hunyuan3D-2.1 with ComfyUI on Windows
- Overview
- Prerequisites
- Installation Steps
- Optional Features
- Troubleshooting
- Quick Reference
- Additional Resources
This guide provides a complete installation walkthrough for Hunyuan3D-2.1 using ComfyUI Portable v0.3.45 on Windows with NVIDIA RTX GPUs.
⚠️ GPU Requirement:
Hunyuan3D-2.1 requires an NVIDIA RTX 30-series or newer GPU.
RTX 20-series GPUs (including RTX 2060) are not supported by the provided CUDA extensions.
Important: This guide is specifically validated for:
- Windows operating system
- NVIDIA RTX GPU (CUDA support required)
- ComfyUI Portable (NVIDIA) v0.3.45
Before starting, ensure you have the following installed:
Required:
- NVIDIA GPU with CUDA support
- Compute Capability ≥ 8.0 (Ampere or newer architecture)
- 8 GB VRAM minimum (12–24 GB strongly recommended)
✅ Supported GPUs:
- RTX 30-series (3060, 3070, 3080, 3090)
- RTX 40-series (4060, 4070, 4080, 4090)
- RTX A-series (A2000, A4000, A5000, etc.)
❌ Not Supported:
- RTX 20-series (2060, 2070, 2080)
- GTX 10-series
- GTX 16-series
- Any GPU older than RTX 30-series
📋 Detailed GPU Requirements & Technical Information
- 8 GB VRAM — Minimum requirement
- 12–24 GB VRAM — Strongly recommended for stable generation and higher resolution meshes
⚠️ Warning: Unsupported GPUs may launch ComfyUI successfully but will fail during generation with errors such as:CUDA error: no kernel image is available for execution on the deviceThis occurs because the Hunyuan3D custom rasterizer CUDA extension is compiled without support for SM 7.5 (Turing) and older architectures.
Hunyuan3D-2.1 relies on a precompiled CUDA rasterizer kernel (custom_rasterizer_kernel) for performance. The distributed Windows wheels are typically built for newer GPU architectures only (Ampere+).
What happens with unsupported GPUs:
- ✅ Python and ComfyUI will start normally
- ✅ Model loading may succeed
- ❌ Generation will fail as soon as the rasterizer kernel is invoked
Users with unsupported GPUs may attempt to:
- Rebuild the rasterizer from source with
TORCH_CUDA_ARCH_LIST=7.5 - Use a workflow that does not invoke the rasterizer
Note: These approaches are not officially supported and are outside the scope of standard installation.
Download the exact build required:
ComfyUI Windows Portable (NVIDIA) v0.3.45
Extraction location example:
X:\ComfyUI_windows_portable_nvidia
Critical: Do not mix ComfyUI versions. All steps are validated against v0.3.45 only.
Download CUDA 12.6 (Windows x64)
Note: Reboot your system after CUDA installation is complete.
Download Visual C++ Build Tools
Required components:
- MSVC v143
- Windows 10/11 SDK
- CMake tools
Open Command Prompt and navigate to:
ComfyUI_windows_portable\ComfyUI\custom_nodes
git clone https://github.com/visualbruno/ComfyUI-Hunyuan3d-2-1git clone https://github.com/visualbruno/ComfyUI-Hunyuan3DWrapperCritical: This workflow requires KJNodes, but newer versions are incompatible due to
comfy_api.latestchanges.
git clone https://github.com/kijai/ComfyUI-KJNodes.git
cd ComfyUI-KJNodes
git checkout 37a0973
cd ..Important:
- Do not update KJNodes after this step
- Do not use "Update all" in ComfyUI-Manager
- This commit (37a0973) is the last known compatible version
Download: Hunyuan3D-2.1 Diffusion Model (model.fp16.ckpt)
Rename to: hunyuan3d-dit-v2-1.ckpt
Place in:
ComfyUI\models\diffusion_models\
Download: Hunyuan3D-2.1 VAE Model (model.fp16.ckpt)
Rename to: hunyuan3d-vae-v2-1.ckpt
Place in:
ComfyUI\models\vae\
Critical: All installations must use ComfyUI's embedded Python.
Navigate to the ComfyUI portable root:
ComfyUI_windows_portable
python_embeded\python.exe -m pip install ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\wheels\custom_rasterizer-0.1.0+torch260.cuda126-cp312-cp312-win_amd64.whlpython_embeded\python.exe -m pip install ComfyUI\custom_nodes\ComfyUI-Hunyuan3d-2-1\hy3dpaint\DifferentiableRenderer\dist\mesh_inpaint_processor-0.0.0-cp312-cp312-win_amd64.whlpython_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\ComfyUI-Hunyuan3d-2-1\requirements.txtpython_embeded\python.exe -m pip install pytorch_lightning opencv-python rembgIf rembg installation fails:
python_embeded\python.exe -m pip install --upgrade onnxruntime pillow numpy
python_embeded\python.exe -m pip install rembgIf you're upgrading from version 2.0:
python_embeded\python.exe -m pip uninstall -y timm
python_embeded\python.exe -m pip install --no-cache-dir "timm>=0.9.12"From the ComfyUI portable root folder, run:
run_nvidia_gpu.batAccess ComfyUI in your browser:
http://127.0.0.1:8188
Background removal is handled by rembg (installed in Step 3.4).
Note: You do not need MVAdapter unless your specific workflow explicitly requires it.
If a workflow references RMBG:
- Ensure
rembgimports without errors - Restart ComfyUI if needed
Solution:
python_embeded\python.exe -m pip install rembgIf this fails, upgrade dependencies first:
python_embeded\python.exe -m pip install --upgrade onnxruntime pillow numpy
python_embeded\python.exe -m pip install rembgCause: KJNodes version is too new for ComfyUI core.
Solution:
cd ComfyUI\custom_nodes\ComfyUI-KJNodes
git checkout 37a0973
cd ..\..Do not update KJNodes after fixing this.
Cause: KJNodes is not loading properly.
Solution:
- Check ComfyUI console for errors:
IMPORT FAILED: ComfyUI-KJNodes - Verify KJNodes is pinned to commit
37a0973 - Restart ComfyUI
- If issues persist, re-clone and pin KJNodes:
cd ComfyUI\custom_nodes
rmdir /s /q ComfyUI-KJNodes
git clone https://github.com/kijai/ComfyUI-KJNodes.git
cd ComfyUI-KJNodes
git checkout 37a0973Cause: OpenCV is installed without the "contrib" modules. The ximgproc module is part of OpenCV's extended functionality and requires opencv-contrib-python instead of the standard opencv-python.
Solution:
Navigate to the ComfyUI portable root folder (the folder containing python_embeded\, ComfyUI\, and run_nvidia_gpu.bat).
Remove regular OpenCV (if installed):
python_embeded\python.exe -m pip uninstall -y opencv-pythonInstall OpenCV contrib build (includes ximgproc):
python_embeded\python.exe -m pip install --upgrade opencv-contrib-pythonRestart ComfyUI after installation.
If it still fails, do a clean reinstall:
python_embeded\python.exe -m pip uninstall -y opencv-python opencv-contrib-python
python_embeded\python.exe -m pip install --no-cache-dir --force-reinstall opencv-contrib-pythonImportant: Always use ComfyUI's embedded Python (
python_embeded\python.exe). Running pip on system Python will not affect ComfyUI Portable.
The example workflow file is located at:
ComfyUI\custom_nodes\ComfyUI-Hunyuan3d-2-1\workflow_examples\Full_Workflow.json
Load this file from within the ComfyUI interface.
- Always use ComfyUI's embedded Python for package installations
- Keep ComfyUI core and custom nodes in sync (v0.3.45)
- Avoid auto-updating custom nodes (especially KJNodes)
- Do not use "Update all" in ComfyUI-Manager
Made for the ComfyUI community
If this guide helped you, consider giving it a star!